Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 001a / com_and2.zip / CASCRIPT.DOC < prev next >

Wrap

Text File | 1990-10-16 | 262KB | 8,580 lines

COM-AND: IBM PC Communication Script Language ------------------------------------------ COM-AND: Communications Script Language for the IBM PC ------------------------------------------ COM-AND is distributed freely and may be copied by anyone for any number of machines, for purposes of evaluation. The author offers COM-AND and its accessory programs as a package, as "shareware". If you USE the program a registration of $35.00 is required. The author may be reached: CABER Software R. (Scott) McGinnis P.O. Box 3607 Mdse Mart Chicago, IL 60654-0607 PLINK, GEnie id: TARTAN CIS id: 73147,2665 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language COM-AND version 2.7 is copyright 1990 CABER Software (R. Scott McGinnis). All rights are reserved world wide, excepting redistri- bution under the ShareWare concept. COM-AND is distributed freely and may be copied by anyone for any number of machines, under the ShareWare concept. COM-AND is distributed as ShareWare. You may use COM-AND without charge for the purposes of evaluating its usefulness to you. It is suggested that this evaluation period be limited to a few days of actual use. If you find COM-AND to be worth continued use, then you are asked to pay for it. The payment is called a "registration fee". Complete the included registration form and mail it with your payment. Registration of COM-AND includes all published accessory programs (which currently are PC-VCO, CCHESS, CBRIDGE, and CCOLOR), and several utilities (unPACKIT and unSTUFIT). Accessories and utili- ties are published separately. One registration covers the use of any and all of these programs. By registering your copy of COM-AND (or any ShareWare product), you are promoting and supporting the convenient distribution method and free evaluation policy that brought you this copy of COM-AND. If you have received this copy from a Users' Group, "Software Library" or "SIG", and have paid a small fee (usually $3 to $10), you have NOT acquired a registration or continued right to use COM-AND. This fee was for the convenience of obtaining the diskette with COM-AND on it. The fee does NOT apply to the registration fee. You may NOT distribute COM-AND or its documentation in connection with ANY commercial venture, product, publication or service without written approval. COM-AND may not be disassembled or modified without express written consent of its author. COM-AND is supplied "as-is" with no warranties expressed or implied. Neither CABER Software nor the author will be liable for any damages or lost revenues incurred through the use of this program or any of its accessories and utilities beyond the registration price paid. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language COM-AND version 2.7 is available as shareware through PLINK, GEnie, UNISON, NWI, Delphi and CIS. COM-AND is also available through many Bulletin Board systems. Individuals are welcome to download COM-AND for purposes of evaluation. Commercial users of COM-AND must register COM-AND with the author or one of the individuals listed here. Site licenses (multiple copy registrations) are available from: CABER Software R. (Scott) McGinnis P.O. Box 3607 Mdse Mart Chicago, IL 60654-0607 PLINK, GEnie, Delphi ID: TARTAN CIS id: 73147,2665 Commercial users of COM-AND may register it with the author above or through: SupportWare Mike Todd P.O. Box 14927 Long Beach, CA 90803-1449 (213) 439-6104 In Japan, COM-AND may be downloaded as shareware from PC-VAN. COM-AND is available in Japan as a commercial product tailored for specific machines through: Discotel Japan (Ciari Soft) Kurakuen 3 ban-cho 2-50 Nishinomiya 662 Japan Contact: Claude Ciari Tel (0798)73-0052 PC-VAN NEC by Ciari ID: CCIARI Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Table of Contents ----------------- I. COM-AND Introduction ...................................... page 1 II. Script Introduction ....................................... page 2 III. Definitions ............................................... page 4 A. Comments ................................................ page 4 B. Labels .................................................. page 4 C. Keywords ................................................ page 5 D. Commands ................................................ page 5 E. Strings ................................................. page 6 F. Numerics ................................................ page 7 G. States .................................................. page 8 IV. Syntax .................................................... page 9 V. Script Language Commands ................................... page 11 Commands beginning "A"...................................... page 11 Commands beginning "B"...................................... page 14 Commands beginning "C"...................................... page 15 Commands beginning "D"...................................... page 20 Commands beginning "E"...................................... page 26 Commands beginning "F"...................................... page 29 Commands beginning "G"...................................... page 39 Commands beginning "H"...................................... page 43 Commands beginning "I"...................................... page 44 Commands beginning "J"...................................... page -- Commands beginning "K"...................................... page 52 Commands beginning "L"...................................... page 52 Commands beginning "M"...................................... page 54 Commands beginning "N"...................................... page 58 Commands beginning "O"...................................... page 59 Commands beginning "P"...................................... page 61 Commands beginning "Q"...................................... page 62 Commands beginning "R"...................................... page 63 Commands beginning "S"...................................... page 66 Commands beginning "T"...................................... page 76 Commands beginning "U"...................................... page 78 Commands beginning "V"...................................... page 78 Commands beginning "W"...................................... page 79 Commands beginning "X"...................................... page -- Commands beginning "Y"...................................... page -- Commands beginning "Z"...................................... page -- Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Table of Contents ----------------- VI. SET Commands .............................................. page 84 A. Basic set ............................................... page 84 B. SET ASCII ............................................... page 98 C. SET KERMIT .............................................. page 99 D. SET ZMODEM .............................................. page 101 VII. String Intrinsics ......................................... page 102 VIII. Script Errors .............................................. page 106 IX. ASPECT and PROCOMM 2.4.2 scripts ........................... page 107 X. Program Requirements ....................................... page 109 XI. Program and Author Information ............................ page 110 Appendices ---------- A. Sample scripts ............................................ page 111 B. Host and BBS scripts ...................................... page 114 C. External Protocol Drivers ................................. page 115 D. Encoded Music ............................................. page 117 E. File transfer error numbers ............................... page 120 F. EBL ....................................................... page 122 G. Manual setting and scripts ................................. page 123 1. Alt-S (Setup window) .................................... page 123 2. Alt-O (Options window) .................................. page 124 3. Alt-P (Parameters window) ............................... page 125 4. Alt-K (KERMIT defaults window) .......................... page 125 5. Alt-J (Colors window) ................................... page 126 6. Help (General Help list) ................................ page 126 H. STACK and Macro keycodes .................................. page 128 I. Dynamic string variables ................................... page 129 J. Flow control methods ....................................... page 131 K. Machine language subroutines ............................... page 133 L. CACMP ...................................................... page 136 M. Script Language (version 1.x) .............................. page 137 N. Language Summary ........................................... page 140 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 1 I. COM-AND Introduction COM-AND for the IBM PC and compatibles is a communications program that may be used by itself, or with several integrated accessory programs (which themselves may be used independent of COM-AND). COM-AND provides standard comm program functions: a dialing directory, macros, disk logging, binary and ASCII file transfers, and most particularly: scripted execution. COM-AND Version 2.7 executes as a CRT based comm program either in 25 line text mode on a CGA or monochrome screen, or 25/43 line mode on an EGA display. When an accessory is loaded through COM-AND (or when COM-AND is loaded by an accessory), most of the functions of COM-AND are available through the accessory. COM-AND and its accessories (PC-VCO, CCHESS, CBRIDG, and CCOLOR) may be copied freely and distributed to anyone for any number of machines. The author offers COM-AND as "shareware". If the program is used after a reasonable period of evaluation, a registration of $35.00 is asked for the entire package. COM-AND provides a script language for automation of certain tasks. COM-AND is distributed with a KERMIT server, a HOST mode, a Bulletin board, a file manager, and a LEARN MODE... all as scripts. Scripts may be written for COM-AND by anyone, requiring only an editor that produces ASCII files. COM-AND will execute scripts written for the very popular PROCOMM communication program as well. This document discusses scripted execution, and the COM-AND Script Language. The script language has grown over the years to the point where its documentation requires a separate manual. For manual use of COM-AND, and functional overview, the reader is refered to the document COM-AND.DOC. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 2 II. Script Introduction A script facility allows certain manual tasks to be automated, and COM-AND to run unattended (if you have tested the script !!!). Scripting is invoked in several ways: o at load time: . COM-AND.CMD, if present in the current directory or the subdirectory indicated by the 'COM-AND=' environment variable, is executed immediately; . the /F switch in the run command may specify a script to be executed immediately (after COM-AND.CMD, if present); o interactively (through F2) as a script o interactively (through F1) as an accessory or part of one o a script may be attached to a dialing directory entry, to be executed upon successful connection Script commands are read by COM-AND from an ASCII file (word processor files are not usually ASCII files!). Programmer's text editors and EDLIN (provided with DOS) may be used to create and modify a script file. If you wish to use a word processor to update a script, first ensure that the particular word processor will output an ASCII file (often called non-document format, perhaps even called ASCII). Once a script begins, execution of COM-AND is automatic, driven by the script. However, the ESC key may be used to terminate the script at most any time (depending on the script. The script author might make ESC unusable). During dialing, two ESCs are needed... one to terminate the dial function, and the second to end script. Generally speaking, a script usually takes the form: <perform some action> <wait for an identifiable response> <perform some action... ... and so on Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 3 II. Script Introduction (continued) For example, a script might dial a number listed in the dialing directory and wait for the "ID = " response from the dialed host. The next action would be to send the logon ID, with a carriage return and await a prompt for a password. The scripts included with COM-AND are examples of such simple scripts. However: the COM-AND script language is not limited to communications related tasks... programs may be loaded and passed parameters, screen windows may be opened and scrolled, and so on. A nontrivial BBS has been written using COM-AND's scripting, and is provided with the distribution for the interested (and wary)! It is taken for granted that the script programmer is acquainted with the computer and telecommunications environment in general, and the COM-AND program in particular. Much of the script language facility revolves around making the features of COM-AND available to the programmer. After that, the remainder of the language makes the computer (e.g. read and write files), and the communications line (e.g. read and write lines of text) available to the programmer. Details of the features of COM-AND are discussed in the COM-AND.DOC document. Much of the discussion to follow assumes familiarity with that document. The next few pages define terms used in discussing scripts and script language elements. Notational symbols will then be defined. After that, script language elements will be presented in detail. Appendix I summarizes the version 1.x script language. Appendix J summarizes the version 2 and 3.x languages. Sample scripts are presented in Appendix A. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 4 III. Definitions A. Comments: Comments may be used (and are highly recommended!) alone on a line, on a command line (after the command) or on a label line (after the label). A comment begins with a semi-colon or asterisk and extends to the end of the line. Blank lines are also treated as comments, for phrasing. Top-of- form, appearing in the first column, is treated as a comment. B. Labels: Labels are character strings terminated with a colon, not including the characters: blank, comma(,), exclamation (!), number sign (#), dollar sign ($), percent sign (%), ampersand (&), apostrophe ('), double quote ("), left and right parenthesis, asterisk (*), plus (+), hyphen (-, minus), right slash (/), and semi-colon(;). Only the first 8 characters of the label are significant to the script processor; if two labels match for the first 8 characters, the one closest to the beginning of the script will be used, and the second ignored. Case is not significant in labels. Comments are allowed on a line with a label (comments begin with semi-colon or asterisk and extending to the end of the line). Commands are not allowed on a line with a label. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 5 III. Definitions (continued) C. Keywords: Keywords are alphanumeric character strings terminated by a blank, a comma, a left parenthesis, or a semi-colon. Only the first 4 characters of the keyword are significant to the script processor (where keywords are the same for the first 4 letters, the last letter is used to distinguish them). Case is not significant in keywords. D. Commands: Commands are structured: <keyword> followed by arguments (if any). Delimiters between command arguments are blank and comma. Each command is a line by itself (with the exception of the IF statement which may contain a second command). Comments are allowed after the command (comments begin with semi-colon or asterisk and extend to the end of the line). COM-AND implements a stack for GOSUB, IF, SWITCH, FOR, DO and WHILE commands. This allows these commands to be nested to 20 levels. A 'stack overflow' message is issued when nesting of more than 20 is attempted. A 'stack underflow' message is issued when a RETURN is encountered for which no corresponding GOSUB was issued. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 6 III. Definitions (continued) E. Strings: String arguments are of two kinds: literal and variable. Literal strings are enclosed in double quotes ("). The accent grave (`) is used in a literal string to force the next character (e.g. the string "`"" is a literal consisting of a double quote by itself). String variables are refered to as S0, S1, ... S29. Each string variable is 80 characters wide, and may be set with the Sx=, ASSIGN, GET, and RGET statements. They are set to blank when the script begins (but are not reset to blanks when EXECUTE or FCALL moves the script processor to a new script file). Strings are manipulated internally exactly as given. However, when issued (to the console or out the comm port, or in some cases to disk), or used in WHEN string, certain edits are performed: o Trailing blanks are trimmed o "!" by itself (except "!!") is translated into a carriage return o "^x" (except ^^) where 'x' is character "@" through "`" is translated into the corresponding control character o Certain strings are treated as "intrinsic"s. Refer to chapter VII of this document for further discussion. Refer below to the "Sx = <expression>" discussion on page 76 for details on string expressions. Another set of string variables may be dynamically allocated by a script (or scripts). These variables are refered to as V0, V1, ... Vx, where 'x' is determined by the allocating script. Dynamic string variables may be used anywhere static variables are used, AFTER A SCRIPT ALLOCATES THEM. Refer to appendix 'I' for a discussion of these variables and their use. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 7 III. Definitions (continued) F. Numerics: Numeric arguments are of two kinds: literal and variable. Lit- eral numerics are values alone or within double quotes, or as a string within a string variable. Decimal values with the range -32,768 to 32,767 are supported. Hexadecimal values may be specified using the 'C' convention (e.g. 0xffff is -1). Numeric variables are refered to as N0, N1, ... N99. Each numeric variable is capable of storing the value -32,768 to 32,767. They are set to zero when the script begins (but are not reset to zeroes when an EXECUTE or FCALL statement moves the script processor to a new script file). Refer below to the "Nx = <expression>" discussion on page 58 for details on numeric expressions. Numeric expressions are allowed in place of single numeric values (where a value is required) in all commands except: ADD, SUB, MUL and DIV, IF EQ/LT/... and IF ZERO. An expression may be used in these commands only if it is entirely contained within parentheses. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 8 III. Definitions (continued) G. States: o String variables are set to blank at the start of a script. o Numeric variables are set to zero at the start of a script. o EXECUTE does not reset string or numeric variables or clear any conditions (SUCCESS/FAILED/WAITFOR/etc). Neither does EXECUTE clear WHEN settings. o EXECUTE clears any IF and SWITCH function and GOSUB stack. o FCALL does not allow 'branch-back' from a called file to a label in the calling file. FCALL does not reset the ON ESCAPE implicit GOSUB (which potentially is a branch-back), so be careful!. o GOTO must not be used to enter an IF clause or SWITCH case, even from within an IF clause or SWITCH. o Received text is not processed until RGET, PAUSE or WAITFOR instructions are performed. o Keystrokes entered during a script are transmitted out the comm port (unless HITKEY or SET TTHRU has been invoked). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 9 IV. Syntax The chapter defines symbols that will be used in command syntax descriptions. Of necessity, some will seem cryptic at first... bear with me, please. -> Author's note. The command highlighted with '->' IS compatible with ASPECT scripting. * Author's note. The command highlighted with '*' is documented for ASPECT compatiblity, but not implemented in this version of COM-AND. [A] optional keyword A (A!B!C...) Required choice: A or B or C ... Sx String variable S0,S1,S2...S29 Nx Numeric variable N0,N1,N2...N99 -> <label> Label identifier (1) literal value (e.g. LABEL) -> (2) a string variable (e.g. S0) -> containing a label name (3) a quoted string (e.g. "...") -> <string> Textual value, i.e. (1) a quoted string (e.g. "...") -> (2) a string variable (e.g. S0) (3) a substring (e.g. S0(4:5), being position 4 through 5) (4) a string expression -> <number> Numeric value, i.e. (1) a quoted number (e.g. "4") -> (2) a literal number (e.g. 555, or hex value e.g. 0xff) -> (3) a numeric variable (e.g. N5) (4) a string variable (e.g. S0), which contains the value. (5) a numeric expression <row> Numeric value representing a row number (0-24 or 0-42 according to the screen mode). Expressions (e.g. N0+1) are legitimate and accepted. <col> Numeric value representing a column number (0-79). Expressions are legitimate and accepted. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 10 IV. Syntax (continued) <len> Numeric value representing a length (0-79). Expres- sions (e.g. N0+1) are legitimate and accepted. <color> Color keyword or value. These are: 0 Black 8 DkGrey (Dark Grey) 1 Blue 9 LtBlue 2 Green 10 LtGn (Light Green) 3 Cyan 11 LtCyan 4 Red 12 LtRed 5 Magenta 13 LtMagenta 6 Brown 14 Yellow 7 LtGrey (Light Grey) 15 White DEFAULT: This keyword specifies the foreground/ background attr set through Alt-J for menues. CONTRAST: This keyword specifies the foreground/ background attr (reversed) as specified through Alt-J for menues. TEXT: This keyword specifies the foreground/ background as specified through Alt-J for text. TCONTRAST: This keyword specifies the foreground/ background (reversed) text as specified in Alt-J. -> <attr> A foreground/background attribute. This may be -> of two forms: 0-255 (background value*16+foreground) and: ([<color>] <color>). or ([DEFAULT] DEFAULT) or ([CONTRAST] CONTRAST) or any mix of the above For example "15" and "(black white)" are equivalent attributes to COM-AND. "(DEFAULT)" sets the attribute the default set through Alt-J for menu windows. # A single digit (#) A digit within literal parenthesis Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 11 V. Script Language Commands ACCESSORY <string> or ACCESSORY <number> The ACCESSORY statement invokes the accessory directory to (optionally) execute a new script, and (optionally) load a program. The accessory directory entry number specified is in <string>. <String> is formatted exactly as with the F1 menu; it consists of an entry number 1-50. Examples: ACCESSORY 1 ; Load entry 1 ; Nothing past this point in the script will be performed. Each accessory entry specifies: o A drive:subdirectory (optional) o A script to be executed (optional) o A program invocation (optional) Accessory entries are constructed and modified with the 'r' sub- command of the F1 menu or SET ACCESSORY script commands. The ACCESSORY command terminates the current script file. The current script file is closed (and not re-entered when the new file completes). Any IF/GOSUB/SWITCH commands in effect are cleared. Unlike EXECUTE, all strings and conditions are cleared when the Accessory script (if there is one) begins. Parameters may not therefore be passed to an accessory script (yet!). -> ADD Nx Ny Nz The ADD command performs the instruction: Nz = Nx+Ny. No error checking is performed; should the value exceed the range of a numeric variable, results are unpredictable. Example: -> ADD N1 N2 N3 ; N3 = N1+N2 An expression may be used for Nx or Ny if it is entirely contained within parentheses. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 12 V. Script Language Commands (continued) -> ALARM [<number>] The ALARM command sounds COM-AND's alarm. The alarm continues for the time in seconds specified through the Alt-S 'Display duration', unless overridden by the optional numeric argument. Any keypress terminates the alarm. Example: -> ALARM 10 ; Annoy for 10 seconds ALOAD <string> The ALOAD statement loads a new Accessory Definition file (F1). The ALOAD command requires a file name in <string>. <String> contains an unqualified file.ext (or may contain -> a fully pathed file name). Example: ALOAD "COM-AND.ACC" ; Load original accessory def ALOAD "C:\SOURCE\COM-AND.ACC" ; Load special definitions Note: The file name is limited to 27 characters in length. ALLOCATE <number> The ALLOCATE statement allocates up to 100 dynamic variables referenced V0, V1, ... for use by the current and subsequent scripts. ALLOCATE returns success/failure according to avail- able memory. Please refer to Appendix I for a discussion of dynamic allocation of variables. Example: ALLOCATE N0 ; Allocate a dynamic area Note: The number of dynamic variables is limited to 100. ANAME Sx <number> The ANAME command returns the name field from the accessory directory. A directory number (1-50) must be specified. Example: ANAME S0 5 ; Fetch the name from # 5 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 13 V. Script Language Commands (continued) APGM Sx <number> The APGM command returns the program invocation field from the accessory directory. A directory number (1-50) must be speci- fied. Example: APGM S0 5 ; Fetch the pgm from # 5 ASCRIPT Sx <number> The ASCRIPT command returns the script field from the accessory directory. A directory number (1-50) must be specified. Example: ASCRIPT S0 5 ; Fetch the name from # 5 -> ASSIGN Sx <string> The ASSIGN statement allows a string variable to be set to a value. The value may be another string variable, a literal textual value (a quoted string), or a substring. Examples: -> ASSIGN S0 "MAIL" ; S0 now contains "MAIL" -> ASSIGN S1 S0 ; S1 now contains "MAIL" ASSIGN S2 S0(0:1) ; S2 now contains "MA" (char0:char1) ASUBDIR Sx <number> The ASUBDIR command returns the subdirectory field from the accessory directory. A directory number (1-50) must be specified. Example: ASUBDIR S0 5 ; Fetch the subdir from # 5 -> ATGET row col attr len Sx The ATGET statement performs the GET function, i.e. reading the keyboard for a length, with cursor positioning and color control. Example: -> ATGET 0 0 15 5 S5 ; Read up to 5 chars into S5 from 0,0 ATGET 0 0 (black white) 5 S5 Note that the cursor is left positioned after the last character read. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 14 V. Script Language Commands (continued) -> ATOI Sx Nx The ATOI statement converts a value in a string variable to a numeric variable. If no numeric value is found, or the value -> exceeds the range for numeric variables, the ERROR flag is set. Examples: -> ASSIGN S0 "1234" ; S0 now contains "1234" -> ATOI S0 N1 ; N1 now contains 1234 ATOI S2(2:3) N2 ; N2 now contains 34 (char2:char3) -> ATSAY row col attr <string> The ATSAY statement performs the MESSAGE function, i.e. writing to the screen, with cursor positioning and color control. Example: -> ATSAY 0 0 15 "text" ; Write at 0,0; white on black ATSAY 0 0 (black white) S5 Note that the cursor is left positioned after the last character written. ATSCR row col len Sx The ATSCR statement reads the screen starting at the position indicated by <row> and <col>, for the length specified into the string variable Sx. The screen display characters (not their color attributes) are copied into Sx. Example: ATSCR 2 0 80 S5 ; Read the whole of line 2 into S5 -> BOX row col row col attr The BOX statement draws a box over a region on the screen, filling the space within with a specified color. The first and second arguments specify the row/column of the top-left of the region. The third and fourth arguments specify the row/column of the bottom-right of the region. The last argument specifies the color attribute to be used for the characters written. -> BOX 0 10,10 20,20 15 ; White on black: narrow box BOX 0 10,10 20,20 (black white) Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 15 V. Script Language Commands (continued) -> BREAK [<number>] The BREAK statement performs a true break. The length of the BREAK is set (by default) through the Alt-S menu. The length of the signal optionally may be specified in milliseconds. Example: -> BREAK 1500 ; Send a 1.5 second break -> BYE The BYE statement terminates both the script and COM-AND, leaving DTR as-is (connection, if made, is not broken). It may be coded at any level (for example within a subroutine reached through a call from a subroutine). Example: -> BYE ; Leave connection open ; Nothing past this point in the script is executed Note also the QUIT command. -> CASE (<string>!<numeric>) The CASE statement must be contained within the domain of a SWITCH/ENDSWITCH pair. The CASE statement specifies a value against which the string variable identified is tested. Case is not significant in the comparison. If the variable matches the given string (shift case excluded), the statements following the CASE will be executed, until an ENDCASE is encountered. Refer to SWITCH for an example. Note that the argument of a CASE statement may be a literal or variable value. Both string and numeric variables are allowed. String substring extraction (e.g. S0(5:10)) is also supported. -> CHDIR <string> The CHDIR statement changes the current default subdirectory used for unqualified file name references. Examples: -> CHDIR "\COM-AND" ; Change path on the current drive CHDIR "C:\COM-AND" ; Change drive and path Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 16 V. Script Language Commands (continued) -> CLEAR [<attr>] The CLEAR statement clears the screen. It optionally changes the background and foreground colors. The <attr> argument specifies a new background color (if present), and a new foreground color. Note that a foreground argument requires a background argument. Example: -> CLEAR 15 ; Clear screen, set white on black CLEAR (BLACK RED) ; Clear screen, set red on black CLEAR ; Clear screen, leave colors alone CLEAR sets the cursor to the top left of the scrolling region, either as defined by default, or through the DWINDOW command. CLOG OPEN <string> CLOG CLOSE CLOG <string> The CLOG subcommands OPEN a call-log file by name, CLOSE an open call-log file, and write to the call-log (if open). The CLOG OPEN command requires a file name. The <string> is limited to 26 characters in length. It may contain a fully pathed file name. The given name will be searched for on the current drive:subdirectory and the one specified by the 'COM-AND=' environment variable. Example: CLOG OPEN "Log.txt" ; Open calllog file and start logging CLOG OPEN "E:log.txt" ; Open calllog on RAM drive CLOG OPEN sets the SUCCESS/FAILURE condition (tested with the IF statement). Note that the script write may choose to open a call-log file by name (closing the default call-log, if one is established) or alternatively to accept the user's discretion in the matter. The CLOG command writes to the call-log only if it is open. If the script writer does not open the call-log (CLOG OPEN or SET CALLLOG ON), CLOG commands will be ignored unless call-logging has been enabled BY THE USER. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 17 V. Script Language Commands (continued) -> COLOR <attr> The COLOR statement changes the foreground (and optionally the background display colors. The first argument specifies a new background color. The second argument specifies a new fore- ground color. Note that a background argument requires a fore- ground argument. Example: -> COLOR 15 ; Set white on black COLOR (0 15) ; Set white on black COLOR (BLACK RED) ; Set red on black COLOR (RED) ; Set foreground to red COMBASE <port> Nx The COMBASE statement returns the base address for the given port (port is COM1, COM2...). This value may be set through Alt-P (manually) or SET COMBASE in a script. COMBASE COM1 N0 ; Read current base address COMPARMS Sx The COMPARMS statement returns the current communications parameters, formatted: "bbbb,p,d,s,COMx" where "bbbb" is baud rate, "p" is parity (E/O/N), "d" is the number of data bits (7/8), "s" is the number of stop bits (1/2), and "COMx" is the comm port. Example: COMPARMS S4 ; Read current settings COMVECTOR <port> Nx The COMVECTOR statement returns the vector # (0-7) for the given port (port is COM1, COM2...). This value may be set through Alt-P (manually) or SET COMVECTOR in a script. COMVECTOR COM1 N0 ; Read current vector # Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 18 V. Script Language Commands (continued) CONCAT Sx [(##)!*] <string> The CONCAT statement concatenates two strings. The first string is the target variable (Sx). The second string is the text to be concatenated. Concatenation may take place at a fixed position in the target, or the target may be backscanned for the last nonblank character. Example: S1 = "MAIL" ; Set file name 1st 4 char CONCAT S0 "_DATE"(0:1) ; Take month num from date CONCAT S0 "_DATE"(3:4) ; Take day num from date CONCAT S0(8) ".TXT" ; Add extension at column 8 -> LOG OPEN S0 ; Open log file "MAILmmdd.TXT" Note that "*" may be specified instead of an index (0,1,2...) after the target variable. "*" specifies that the concaten- ation is to be performed without blank trimming. Example: CONCAT S0 * S1 ; Concat S1 at LENGTH S0 -> CONNECT The CONNECT statement terminates a COM-AND script, returning to CRT mode. It may be coded at any level (for example within a subroutine reached through a call from a subroutine). Example: -> CONNECT ; End of script ; Nothing past this point in the script is executed Note also the EXIT and TERMINAL command. CRC <string> Nx The CRC statement computes a CRC for the string given. This CRC might be transmitted after the string to automate error detection and recovery. Example: CRC S0(0:19) N0 ; Compute CRC for 20 characters S0(20:24) = N0 ; Add CRC to the string Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 19 V. Script Language Commands (continued) CTOI <string> Nx The CTOI statement converts a string (1st byte) to a numeric variable. Only a single character is extracted. The value in the numeric variable is the character. Example: S0 = "A" ; Place something in a string CTOI S0 N0 ; N0 now contains a 65 (ASCII "A") -> CUROFF The CUROFF statement turns off the blinking cursor. The cursor will be restored by the CURON command or upon exit. Example: -> CUROFF ; Turn off the cursor -> CURON The CURON statement restores on the blinking cursor. This has no effect unless a CUROFF was performed previously. Example: -> CURON ; Turn back on the cursor -> CURSOR Nx Ny The CURSOR statement reads the current cursor position. Nx returns the row number, and Ny returns the column number. Example: -> CURSOR N0,N1 ; Read current cursor row,col -> CWHEN [(#)] The CWHEN statement clears a WHEN setting. 10 WHEN settings are available (WHEN (0), WHEN (1) ... WHEN (9), with the unquali- fied WHEN equivalent to WHEN(0)). Each must be set and cleared individually. Examples: -> CWHEN ; Clear primary WHEN setting CWHEN (0) ; Same as CWHEN CWHEN (9) ; Clear last WHEN Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 20 V. Script Language Commands (continued) -> DATE Sx [0!1] The DATE statement stores the current system date into the target variable. Example: -> DATE S0 ; Get today's date The date is formatted according to the optional argument (if provided and nonzero, the date is formatted mm/dd/yyyy; otherwise it is formatted mm/dd/yy). -> DBOX row col row col attr The DBOX statement draws a box using double line borders, over a region on the screen, filling the space within with a specified color. The first and second arguments specify the row/column of the top-left of the region. The third and fourth arguments specify the row/column of the bottom-right of the region. The last argument specifies the color attribute to be used for the characters written. Example: DBOX 0 10,10 20,20 (black white) DEALLOCATE The DEALLOCATE statement deallocates dynamic variables if they are currently allocated. Example: DEALLOCATE ; DEALLOCATE dynamic variables -> DEC Nx The DEC command performs the instruction: Nx = Nx-1. No error checking is performed; should the value exceed the range of a numeric variable, results are unpredictable. Example: -> DEC N1 ; N1 = N1-1 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 21 V. Script Language Commands (continued) DECRYPT <string> <string> <string> The DECRYPT command decrypts a file (named in the first arg- ument) to a new file (named in the second argument, which will be purged if it exists) using a 32 character password (the third argument). SUCCESS/FAILURE is set by DECRYPT. Do not decrypt in place! Example: DECRYPT "SECRET.ENF" "COM-AND.EXE" "abcdefghijklmnop" -> DEFAULT The DEFAULT statement must be contained within the domain of a SWITCH/ENDSWITCH pair. The DEFAULT statement specifies a domain of statements to be executed if none of the preceding CASE statements have been executed. The DEFAULT does not have to be the last statement in the SWITCH domain... but should be. The DEFAULT case is terminated when an ENDCASE is encountered. Refer to SWITCH for an example. DEFTIME <number> The DEFTIME statement sets the default delay for the RGET, WAITFOR, and PAUSE statements. <number> is a delay interval in seconds. Example: DEFTIME 60 ; Set original default value back DELETE <file> The DELETE statement deletes a file named in the command. The SUCCESS flag is set according to the result of the command. Example: DELETE "COM-AND.LOG" ; Delete file on the default d:subd Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 22 V. Script Language Commands (continued) -> DIAL <string> or DIAL <number> The DIAL statement invokes the dialing directory to dial the entry number specified in <string>. <String> is formatted exactly as with the Alt-D menu; it consists of an entry number 1-100 prefixed or suffixed by an optional long-distance entry flag. Examples: -> DIAL "1" ; Dial entry 1 -> DIAL "@1" ; Dial entry 1 with long-distance When a dialing directory entry indicates a script to be per- formed, the indicated script is ignored when the number is dialed from within a script. Use the LINKED condition of IF to test this for this condition. [When a script is invoked from Alt-D, LINKED is true.] Dialing is performed as with the redial command (Alt-R). The number is dialed every <RDELAY> seconds (below, see SET), until connection is established, or ESC is pressed. [Note: a script may set a maximum number of redial attempts through SET RDMAX, below. This feature is ONLY available through a script.] The DIAL command sets the FAILED condition if the command was syntactically incorrect or if an ESC was entered to terminate redialing. [Note: The script intrinsic "_RDPN" may be used to determine if the DIAL FAILED after redialing the maximum number of times (if set), or aborted by the user.] -> DIR <string> The DIR statement accepts a string argument as a wildcard template and opens a file display window equivalent to the interactive Alt-F command of COM-AND. Example: -> DIR "*.*" ; Show files on current subdir DIRECTORY Sx (<number>) The DIRECTORY command returns the name field from the dialing directory. A directory number may be specified, or the last dialed entry may be requested. Example: DIRECT S0 5 ; Fetch the name from # 5 DIRECT S1 ; Fetch name of last dialed Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 23 V. Script Language Commands (continued) -> DIV Nx Ny Nz The DIV command performs the instruction: Nz = Nx/Ny. No error checking is performed; should the value exceed the range of a numeric variable, results are unpredictable. Dividing by zero always yields zero. Example: -> DIV N1 N2 N3 ; N3 = N1/N2 An expression may be used for Nx or Ny if it is entirely contained within parentheses. DLDIR Sx The DLDIR statement reads the current download drive:sub- directory into the string variable Sx. Example: DLDIR S0 ; Read the current setting DLOAD <string> The DLOAD statement loads a new dialing directory file (Alt-D). The DLOAD command requires a file name in <string> (up to 27 characters). <String> contains an unqualified file.ext (or may contain a fully pathed file name). Example: DLOAD "COM-AND.DIR" ; Load original dialing dir DLOAD "C:\SOURCE\COM-AND.DIR" ; Load special directory DNUMBER Sx (<number>) The DNUMBER command returns the number field from the dialing directory. A directory number may be specified, or the last dialed entry may be requested. Example: DNUM S0 5 ; Fetch the nbr from # 5 DNUM S1 ; Fetch number last dialed Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 24 V. Script Language Commands (continued) DO The DO statement asserts the beginning of a loop. The end of the loop is signalled by an UNTIL statement (which is evaluated to determine if looping occurs). Example: DO ; Loop until condition below ... UNTIL GE N0,10 ; Loop until N0 >= 10 The condition evaluated by the UNTIL is any condition accepted by the IF statement (including conjunctions of conditions, dis- junction of conditions, and so on). Note: (1) GOTO statements may never enter a DO loop; even to leave an inner loop to return to an outer loop. Note: (2) DO statements may be nested (along with IF, SWITCH, WHILE, and FOR loops) up to 20 levels. However, they may not overlap other DO loops, or other flow-of-control statements. Note: (3) The clause of the DO statement (the statement after 'DO' down to the UNTIL statement) is always execu- ted at least once. The conditional evaluation is not performed until the end of the clause. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 25 V. Script Language Commands (continued) -> DOS <string> [WAIT] The DOS command executes any DOS command. It works by loading a copy of COMMAND.COM (or other SHELL program, as specified by the environment variable COMSPEC=) and passing <string> for execution. Example: -> DOS "dir a:" ; List files on the 'A' drive The optional keyword WAIT signals that COM-AND is to pause after completion for a keypress before the script continues. NOTE: The screen is saved prior to the DOS function, for restoration upon completion. However, the screen size saved is defined by the DWINDOW currently in effect! This command sets the SUCCESS condition (unless the SHELL cannot be found). DPARMS Sx (<number>) The DPARMS command returns the parameters field from the dialing directory, formatted: rrrr,p,d,s,e (where r=rate, p = parity (EON), d = #data bits (7,8), s=#stop bits (1,2) and e=echo (Y,N," "). A directory number may be specified, or the last dialed entry may be requested. Example: DPARMS S0 5 ; Fetch the parms from # 5 DPARMS S1 ; Fetch parms last dialed DSCRIPT Sx (<number>) The DSCRIPT command returns the script file name from the dialing directory (or blanks). A directory number may be specified, or the last dialed entry may be requested. Example: DSCRIPT S0 5 ; Fetch the file from # 5 DSCRIPT S1 ; Fetch script last dialed Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 26 V. Script Language Commands (continued) DWINDOW row col row col DWINDOW CLEAR The DWINDOW command defines a new scrolling region. The first row/col pair define the new top-left, and the second row/col pair define the bottom-right. Example: DWINDOW 10,10,20,70 ; Define a small scroll box DWINDOW CLEAR resets the scrolling region to its maximum size (0,0,23,79 CGA, or 0,0,42/49,79 EGA/VGA). 'Home' cursor position is relative to the current definition of the scrolling region (e.g. CLEAR statement). The region region is returned to 'normal' when a script terminates. SET 43 and SET 25, if executed after DWINDOW, reset the scrolling region and clear the DWINDOW. Note that COM-AND appropriates the last line of the current display for status/LEGEND display unconditionally. NOTE: The DWINDOW defines the screen size for the DOS, RUN and SHELL functions (for screen saves and restoration). DWINDOW should generally be turned off prior to these commands, and reset afterwards. EBL Sx <EBL var> The EBL statement references the global data area maintained by EBL (see Appendix F) if EBL is currently installed. If EBL is not installed, FAILURE is set. If EBL is installed, the given variable (%A through %O, or &<name>) will be returned in Sx, up to 80 characters long (EBL allows up to 127 characters). Example: EBL S0 %B ; Fetch The second variable's value IF FAILURE ... ; Action if EBL not installed Note: The EBL command tests for the environment variable 'BATINT=' before inquiring for EBL's presence. EBL users use environment variables to declare a new (hex) interrupt number. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 27 V. Script Language Commands (continued) EBLSET &<name> Sx The EBLSET statement permits modification (and creation if space permits) of EBL external variables (see appendix F) if EBL is currently installed. If EBL is not installed, or if space does not permit the modification, FAILURE is set. If EBL is installed, the given variable (named '&<name>) will be set to the value in Sx, up to 80 characters long (EBL allows up to 127 characters). Example: EBLSET &USER S0 ; Set ext var to value in S0 IF FAILURE ... ; Action if EBL not installed -> ELSE The ELSE statement must be contained within the domain of an IF/ENDIF pair. Statements following an IF statement are executed if the condition specified was found to be true, and execution continues until an ELSE or ENDIF are encountered. If the condition tested with the IF was found to be false, statements following the ELSE statement (if present) will be executed. Refer to the IF statement for an example. Note that ELSE may contain the statement to be executed on its own line, in which case no ENDIF is required. -> EMULATE (TTY!ANSI!VIDTEX!VT100!VT52) The EMULATE command specifies terminal emulation. COM-AND provides the following emulations (refer to COM-AND.DOC for details): TTY (b/w), ANSI (color), VIDTEX (for CIS), VT-100 and VT-52. Example: -> EMULATE TTY ; Set screen to B&W Note that "EMULATE VIDTEX" is equivalent to "SET ENQ CISB". Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 28 V. Script Language Commands (continued) ENCRYPT <string> <string> <string> [DES!SIMPLE!AUTO] The ENCRYPT command encrypts a file (named in the first arg- ument) to a new file (named in the second argument, which will be purged if it exists) using a 32 character password (the third argument). An optional keyword specifies the method (DES is default). SUCCESS/FAILURE is set by ENCRYPT. Do not encrypt in place! Example: ENCRYPT "COM-AND.EXE" "SECRET.ENF" "abcdefghijklmnop" Note that scripts are automatically decrypted when encountered by COM-AND. You do not need to decrypt a script in order to EXECUTE it (but you may if you wish...). -> ENDCASE ENDFOR -> ENDIF -> ENDSWITCH ENDWHILE The 'END' statements terminate the domain of 'CASE' (and 'DEFAULT'), 'FOR', 'IF', 'SWITCH' and 'WHILE' statements, respectively. [Note, "DO" is terminated by "UNTIL".] Each of these domain statements MUST be paired with its terminating statement. ENVIRON Sx <string> The ENVIRON statement returns the value associated with the variable <string> in the current environment block. Envi- ronment variables are established with the DOS SET command, before COM-AND is entered (SET commands executed through the DOS SHELL have no effect on COM-AND). Example: ENVIRON S5 "COMSPEC=" ; Get current shell pgm name ENVIRON sets and reset the FOUND flag according to operation. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 29 V. Script Language Commands (continued) -> EXECUTE <string> The EXECUTE command chains to a new script file. The current script file is closed (and not re-entered when the new file completes). Any IF/GOSUB/SWITCH/DO/WHILE commands in effect are cleared. Example: -> EXECUTE "newfile.cmd" ; Pick up with a new script ; Nothing past this point in the script will be performed. Note that string variables and conditions are retained as they are when the new script file begins execution. In this way, parameters may be passed to a new script. -> EXIT The EXIT command terminates the script execution. It may be coded at any level (for example within a subroutine reached through a call from a subroutine). Example: -> EXIT ; Terminate the script processor ; Nothing past this point in the script will be performed. NOTE: When the script processor reaches end-of-file, an implicit EXIT is performed. This is true in EXECUTed as well as FCALLed scripts. -> FATSAY row col attr <string> <parms> The FATSAY statement performs the MESSAGE function, i.e. writing to the screen, with cursor positioning and color control. Parameters are formatted into the string provided from the list provided. Example: -> FATSAY 0 0 15 "The answer is %d %s" N0 S0 ; Value and label FATSAY 0 0 (black white) "The answer is %d %s" N0 S0 Note that the cursor is left positioned after the last character written. Refer to the STRFMT statement for discussion of parameter formatting. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 30 V. Script Language Commands (continued) FATTR Sx <file> The FATTR command formats the file attribute byte as binary digits into the target string (Sx). The file name specifi- cation may be a literal quoted string, or a string variable. The formatted string is 8 characters, either 0 or 1. Example: FATTR S3 "COM-AND.EXE" ; Format into S3 The FATTR command sets and resets the SUCCESS flag according to the presence of the named file. The bits returned have meaning: xxxxxxxx ^------------------------ Read-only file ^------------------------- Hidden file ^-------------------------- System file ^--------------------------- File is a volume ID ^---------------------------- File is a subdirectory ^----------------------------- Archive bit for the file ^------------------------------ Always 0 ^------------------------------- Always 0 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 31 V. Script Language Commands (continued) FCALL <file> The FCALL command invokes the file given as if it were a subroutine. If the new file is encrypted, a password will be requested (if the calling file is encrypted, the password to the old file is not requested upon return). Example: FCALL "SUBS.CMD" ; Call a file The called file returns to the caller upon an FRETURN instruc- tion. If end-of-file or EXIT is encountered in the called file, the script terminates. [Note that "IF FCALLed" permits determination that the current file was entered via FCALL.] FCALL does not allow a branch out of the called file back into the caller's file. Labels in an FCALLed file MAY duplicate labels in the caller's file. Note that ON ESCAPE is not reset on entry via FCALL, and unless the new script has the identical label, the script fails (label not found) on escape. For performance purposes, FCALL does NOT close the calling file when the new script file is opened. All script files are closed upon exit... however, a recursion amongst scripts may quickly consume all DOS file handles. Avoid pairs of scripts where each script FCALLs the other. FCALLs may be nested to a depth of up to 10. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 32 V. Script Language Commands (continued) -> FCLOSEI -> FCLOSEO The FCLOSEI and FCLOSEO commands close a file opened for input or output. FCLOSE<I!O> on a file not opened does not hurt anything. When a file is closed, all blocks pending are flushed to the file. Example: -> FCLOSEI ; We're done with it Please note that, when opened for output in TEXT mode, COM-AND does not add a final ^Z (ASCII EOF convention). The script author may choose to precede FCLOSEO with a 'WRITE ^Z"' as need dictates. FDATE Sx <file> [0!1] The FDATE command places the date last modified (as known by DOS) into the target string (Sx). The file name specification may be a literal quoted string, or a string variable. The date is formatted according to the optional format argument (if provided and nonzero, the date is formatted mm/dd/yyyy; otherwise it is formatted mm/dd/yy). Example: FDATE S3 "COM-AND.EXE" 1 ; Format date into S3 The FDATE command sets and resets the SUCCESS flag. FFIRST Sx The FFIRST command initializes a wildcard lookup. If SUCCESS is set after FFIRST, file names may be obtained using the FNEXT command. Only one thread of file name lookups is performed at anyone time; invoking FFIRST when there are more file names to be returned terminates the previous thread. Example: FFIRST "*.asm" ; Initialize lookup Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 33 V. Script Language Commands (continued) -> FGETC Sx -> FGETS Sx The FGETC and FGETS commands read a character (FGETC) or a string (FGETS) into a string variable. The input file must be opened by a previous FOPENI, of course. In TEXT mode, the FGET commands translate CR/LF pairs in the input file to single LFs. No tab expansion is performed. In TEXT mode, the FGET commands stop on an ASCII EOF (Ctl-Z). FGETC reads a single character into Sx(0:0). FGETS reads up to 80 characters into Sx. If the input file was opened in TEXT mode, the read string terminates at the 80th byte or a CR/LF pair (placed in Sx as a single LF). Example: -> FGETS S0 ; Read up to 80 bytes The FGET commands set the EOF condition on input EOF. This may be tested with the IF statement. Note also: FREAD and READ commands. -> FIND Sx <string> [Nx] The FIND command tests for a substring within a target string. Case is not significant. This command sets the FOUND condition for the IF command. Example: -> FIND S0 "sentence" ; Test for the word 'sentence' Note the optional numeric variable argument. If supplied, the index (0,1,2,3...) to the substring within the target string is placed in the indicated numeric variable. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 34 V. Script Language Commands (continued) FNEXT Sx [QUAL] The FNEXT command returns file names from a wildcard lookup. If SUCCESS is set after FNEXT, the given string variable contains the next file name from the template match begun with FFIRST. IF FAILURE is set, the string variable is also set to nulls. Example: FNEXT S0 ; Return name.ext FNEXT S0 QUAL ; Return fully qualified name Wildcard lookup must be initialized with the FFIRST command. The optional 'QUAL' modifier controls whether the returned name is "name.ext" or fully qualified with drive:subdirectory. -> FOPENI <file> [TEXT!BINARY] -> FOPENO <file> [TEXT!BINARY!APPEND] The FOPENI and FOPENO commands open a file for input or output. COM-AND currently supports one file opened for input and one for output at any one time. I/O to/from the file is blocked for fastest access. Files opened for input may be declared TEXT or BINARY in the open statement. The default is TEXT. When the file is opened, it is positioned to the start of the file. Files opened for output may be declared TEXT or BINARY in the open statement. The default is TEXT. On output, unless APPEND is specified, the file is purged if it existed previously. On output, if APPEND is specified, the file is created if it does not exist, and positioned to end-of-file. -> FOPENI "COM-AND.UFL" TEXT ; Open file in text mode FOPENO "COM-AND.LOG" TEXT APPEND; Open file, add to old data The FOPEN commands set the SUCCESS flag according to completion. Refer to FCLOSE, FGET, FPUT, FREAD, FWRITE, READ and WRITE for details of input/output file handling. Also refer to REWIND, FSAVE and FRESTORE for positioning controls. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 35 V. Script Language Commands (continued) FOR Nx = <init> <final> [<step>] The FOR statement asserts the beginning of a loop, controlled by the value of a specific numeric index. The initial value, the final value, and an optional step value are specified. [If a step value is not specified, a step of 1 is used.] The FOR statement initializes the index variable to the given value and performs commands until an ENDFOR is encountered. Upon ENDFOR, the index is incremented (or decremented) by the step value and the result tested against the given final value. If the step is positive, the loop terminates when the index is greater than the final value. If the step is negative, the loop terminates when the index is less than the final value. Example: FOR N0 = 1,10 ; Loop for 10 times ... ENDFOR Note: (1) The STEP and FINAL values are evaluated when the FOR statement is encountered. Changing intermediate values has no effect on the loop. Note: (2) The loop index specified should not be modified within the loop. The results are unspecified if so. Note: (3) GOTO statements may never enter a FOR loop; even to leave an inner loop to return to an outer loop. Note: (4) FOR statements may be nested (along with IF, SWITCH, WHILE and DO loops) up to 20 levels. However, they may not overlap other FOR loops, or other flow-of- control statements. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 36 V. Script Language Commands (continued) -> FPUTC Sx -> FPUTS Sx The FPUTC and FPUTS commands write a character (FPUTC) or a string (FPUTS) from a string variable to the output file. The output file must be opened by a previous FOPENO. In TEXT mode the FPUT commands translate LFs in the string buffer to CR/LF pairs. No tab compression is performed. FPUTC writes a single character from Sx. FPUTS writes up to 80 characters from Sx, according to the length of the value in Sx. Example: -> FPUTS S0 ; Write up to 80 bytes Note also: FWRITE and WRITE commands. -> FREAD Sx Nx Ny The FREAD command reads a string (up to Nx characters) into a string variable. The input file must be opened by a previous FOPENI, of course. In TEXT mode, the FREAD command translates CR/LF pairs in the input file to single LFs, and the read operation ends. No tab expansion is performed. If the input file was opened in TEXT mode, the FREAD commands stop on an ASCII EOF character (Ctl-Z). FREAD reads up to 80 characters into Sx. If the input file was opened in TEXT mode, the read string terminates at the 80th byte or at a CR/LF pair (placed in Sx as a single LF). The count read is placed in Ny. Example: -> FREAD S0 80 N4 ; Read 80 bytes; count read in N4 The FREAD command sets the EOF condition on input EOF. This may be tested with the IF statement. Note also: FGETC/FGETS/READ, and especially notes in READ. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 37 V. Script Language Commands (continued) FREE Sx <string> The FREE statement returns the free space (as a numeric string) on a given disc. The second operand specifies the drive ("" may be used for the default drive) as "d:", where d = a,b,c... Example: FREE S0 "C:" ; Get free space on C: FRESTOREI FRESTOREO The FRESTORE statement restores the last saved position in either the input or output file. The FRESTORE statement sets the SUCCESS flag according to save-stack underflow. See FSAVE below for more detail. Example: FRESTOREI ; Restore last saved position FRETURN The FRETURN command returns returns from an FCALL instruction. The current file is closed, and the previous file (the one containing the FCALL) continues. If the file that invoked FCALL is encrypted, the previous password is NOT requested a second time. Example: FRETURN ; Return to calling file The FCALL stack is limited to a depth of 10 FCALLs. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 38 V. Script Language Commands (continued) FSAVEI [CLEAR!SHIFT!POP] FSAVEO [CLEAR!SHIFT!POP] The FSAVE statement saves the current file position (input or output) on a stack for later repositioning (FRESTORE). Up to 20 positions may be saved for each file. The SUCCESS flag is set/reset according to save-stack overflow. Example: FSAVEI ; To come back later Three subcommands are also provided: FSAVE[I!O] CLEAR ; Zeroes the save-stack FSAVE[I!O] SHIFT ; Shifts the stack down one FSAVE[I!O] POP ; Throws away last saved pos The appropriate file must be open before FSAVE is used. The FCLOSEx (and FOPENx) instruction clears its save-stack. FSIZE Sx <file> The FSIZE command sets the file size (up to seven digits) into the target string (Sx). The file name specification may be a literal quoted string, or a string variable. The SIZE is formatted with leading zeroes blanked and the string right justified in a space of 7 characters. Example: FSIZE S3 "COM-AND.EXE" ; Format into S3 The FSIZE command sets and resets the SUCCESS flag according to the presence of the named file. FTIME Sx <file> [0!1] The FTIME command sets the time last modified (as known by DOS) into the target string (Sx). The file name specification may be a literal quoted string, or a string variable. The TIME is formatted according to the optional format argument (if provided and nonzero, the time is formatted hh:mm:ss where hh is 0-23; otherwise it is formatted hh:mm:ss with a final AM or PM). Example: FTIME S3 "COM-AND.EXE" 1 ; Format military time into S3 The FTIME command sets and resets the SUCCESS flag. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 39 V. Script Language Commands (continued) -> FWRITE Sx Nx The FWRITE command writes a string from a string variable to the output file. The length of the string variable is specified by Nx. The output file must be opened by a previous FOPENO. In TEXT mode the FWRITE command translates LFs in the string buffer to CR/LF pairs. No tab compression is performed. FWRITE writes up to 80 characters from Sx, according to the value in Nx. Example: -> FPUTS S0 75 ; Write 75 bytes Note also: FPUTC/FPUTS/WRITE and especially the WRITE command. -> GET Sx [<number>] The GET command reads the keyboard for text. Text entry is terminated by a carriage return, or, if the optional numeric argument was supplied, after <number> characters. Keyentry is echoed back to the screen. Escape entered in response to the GET command terminates the script. Example: -> MESSAGE "^MEnter a password:" -> GET S0 8 ; Get up to 8 characters Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 40 V. Script Language Commands (continued) -> GETFILE ASCII <string> ; A.K.A. Buffer capture -> GETFILE BYMODEM ; Batch YMODEM -> GETFILE BYMODEMG ; Batch YMODEM-G (BYMOG works too) -> GETFILE CISB ; CompuServe B-protocol -> GETFILE KERMIT ; Kermit or SuperKermit GETFILE QUICKB ; CompuServe Quick B-protocol -> GETFILE RXMODEM <string> ; Relaxed CRC or Checksum XMODEM -> GETFILE WXMODEM <string> ; Windowed XMODEM -> GETFILE XMODEM <string> ; CRC or Checksum XMODEM -> GETFILE YMODEM <string> ; Simple YMODEM (not True ... (TM)) GETFILE ZMODEM ; ZMODEM transfer (batch) The GETFILE statement initiates a download using one of the specified protocols. The <string> argument must specify a valid file name. [If the specified file name exists with one of the XMODEMs, a manual "Purge?" query will pop-up.] The GETFILE command sets SUCCESS/FAILURE condition according to the transfer. Example: -> GETFILE XMODEM "com-and.arc" ; Download Note that, in the cases of CISB, KERMIT,Batch YMODEM (G), and ZMODEM, the host tells COM-AND the name the file will take on your machine. If the name duplicates an existing name, char- acters of the extent are replaced by '$' (right to left). [If ZMODEM recovery is enabled, a ZMODEM transfer picks up where a failed transfer stopped, using the same file name.] Notes: (1) With ASCII transfers, you must manually terminate the capture with ESC. (2) XMODEM and YMODEM (XMODEM1K) automatically purge the target file if found. No manual intervention is required. (3) ZMODEM and CIS-B ( and QuickB) provide an automated download function. The automated function is NOT available within a script unless the script is 'reading the port', i.e. with an RGET, PAUSE or SUSPEND statement. (4) ZMODEM recovery (of a failed transfer) may be enabled and disabled with the SET ZMODEM RECOVER statement. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 41 V. Script Language Commands (continued) -> GOSUB <label> The GOSUB statement transfers control to the label specified in <string>. When a RETURN statement is encountered, execution resumes at the next statement (after the GOSUB). GOSUB commands may be nested to a maximum stack depth of 20. Example: IF FOUND ; Test result of a FIND -> GOSUB "SUB" ; If we found it, transfer to sub -> ENDIF ; .. and return here ... -> EXIT ; End of main-line script ... -> SUB: -> MESSAGE "..." ; Issue a message -> RETURN ; And return to after the GOSUB All of the following are legitimate GOSUB's: -> GOSUB LABEL ; Direct LABEL name -> GOSUB "LABEL" ; Quoted LABEL name ASSIGN S0 "LABEL" ; Assign label name to a string GOSUB S0 ; And goto the label in S0 Note that you cannot GOSUB to a label in a file that has FCALLed the current file. This includes ON ESCAPE GOSUB and ON SILENCE GOSUB conditions (see below). The FCALLed file may however have a label that duplicates one in the caller's file. In the latter case, the GOSUB transfers to the label in the FCALLed file. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 42 V. Script Language Commands (continued) -> GOTO <label> The GOTO statement unconditionally transfers control to the label specified in <string>. If there is more than one <label> in the script file that matches <string> control is transfered to the one nearest the beginning of the script. Example: -> IF FAILURE ; Test previous command execution -> GOTO "ERROR" ; Branch if it didn't work -> ENDIF ; End error test ... -> ERROR: -> EXIT ; Terminate the script Note: GOTO's may be used to transfer control out of an IF, CASE, DO, or WHILE clause. However: GOTO's should never be used to transfer control INTO one or the other clauses of an IF, CASE, DO or WHILE structure. This warning includes transfer out of an IF clause into an enveloping IF clause. "Unexpected ENDIF" or "Unexpected ENDCASE" error messages result from such practice. For example: IF condition ; Example of a nested IF ... IF condition GOTO SKIP_It ; This is INVALID!!! It branches ENDIF ; .. into an IF clause out of one ... SKIP_It: ; This label is within the outer IF ... ; !!! INVALID !!! ENDIF ; End of outer IF Like the GOSUB statement, the operand of a GOTO statement may be a literal label, a quoted label, or a string variable containing the label as text. Note: GOTO's may not be used to transfer control out of a subroutine. "Stack overflows" will eventually be reported if this happens. Note: GOTO's will not exit an FCALLed file to reach a label in a previous file (the caller or caller of caller). The domain of labels used by GOTO is the current script file, and does not include calling files. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 43 V. Script Language Commands (continued) -> HANGUP The HANGUP command terminates the modem connection (if connec- tion has been established). It changes CONNECTED condition (tested with the IF statement, if true CD is enabled on the modem). Example: -> HANGUP ; Disconnect: we're done Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 44 V. Script Language Commands (continued) -> IF [NOT] <condition> [<statement>] The IF statement tests a stated condition, and transfers control according to the result of the test. The IF statement may carry the statement to be performed conditionally, or it may precede statements to be executed if the evaluation is true. In the latter case, and ONLY in that case (where the statements to be conditionally executed follow the IF statement), the script may include an optional ELSE clause, to be executed if the condition evaluated is found false. The domain of this form of IF control is terminated with an ENDIF statement. This construction of the IF statements may be nested up to a maximum stack depth of 20 (with SWITCH DO, FOR, WHILE, and GOSUBs). Example: -> IF <condition> ; Test condition -> GOSUB "TRUE" ; .. execute this if true -> ELSE ; Optional ELSE clause -> GOSUB "FALSE" ; .. execute this if condition false -> ENDIF ; End of IF An equally legitimate construction could be: IF <condition> GOSUB "TRUE" IF NOT <condition> GOSUB "FALSE" Or even: -> IF <condition> ; Test condition -> GOSUB "TRUE" ; .. execute this if true ELSE GOSUB "False" ; ENDIF-less form Please note however, that the following construction is invalid. IF GOSUB "TRUE" ; This statement allows NO ELSE or ENDIF ELSE GOSUB "False" ; Therefore, this statement fails -> IF conditions may be joined with AND, OR, and XOR within one -> IF statement. Parentheticization is also supported. This -> extension will be discussed below, after the conditions are -> listed. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 45 V. Script Language Commands (continued) -> IF <condition> (continued) The optional keyword NOT may precede the condition being tested to reverse its meaning. IF conditions are: ALLOCATED The ALLOCATED condition is true if dynamic var- iables are currently allocated. ALPHA Sx The ALPHA condition tests the first character of the given string. It is true if it finds A-z or a-z. -> CONNECTED The CONNECTED condition is set and reset according to the CD (carrier detect) of the modem. If your modem does not report true CD, then this condition will not be reliable. CONTROL Sx The CONTROL condition tests the first char- acter of the given string. It is true when the character has a value less than 32 (' '). ERROR The ERROR condition is set and reset by the script processor after each command. If the command was syntactically or semantically invalid, this condition is set. -> EOF The EOF condition is set and reset by the last FGETS/FGETC/FREAD/READ statements. -> HITKEY The HITKEY condition is true if a keypress is pending (it will not be read). Note: Use of this function suspends normal type-through until a GET/MGET/ATGET/MATGET/KEYGET/KFLUSH is performed, regardless of value returned. Use of HITKEY may inhibit ESC termination! -> FAILED The FAILED condition is simply "NOT SUCCESS". FCALLED The FCALLED condition tests if the current script file was entered via an FCALL state- ment (if is false unless an FRET is needed). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 46 V. Script Language Commands (continued) -> IF <condition> (continued) FIND Sx Sy [Nx] The FIND condition is actually a FIND per- formed within the IF statement. The syntax and function are identical to the instruction. FKEY The FKEY condition works in a fashion similar to HITKEY. FKEY waits for a function key (not an ASCII key) to be pressed. ASCII keystrokes are typed-through (if TTHRU is on). FLAG [(#)] The FLAG condition tests the current state of flag number # (0-9). Flags are set and with the script instruction SET FLAG. -> FOUND The FOUND condition is set and reset by the last FIND statement. FULL The FULL condition works in a fashion similar to XOFF. FULL is true when COM-AND has XOFFed the other side (SOFT flow control must therefore be ON for this test to be of use). ISDLFILE Sx The ISDLFILE condition is actually a ISDLFILE performed within the IF statement. The syntax and function are identical to the instruction. ISFILE Sx The ISFILE condition is actually a ISFILE performed within the IF statement. The syntax and function are identical to the instruction. ISSCFILE Sx The ISSCFILE condition is actually a ISSCFILE performed within the IF statement. The syntax and function are identical to the instruction. -> LINKED The LINKED condition is true when the script being executed was invoked from a dialing directory entry. -> MONO The MONO condition is true if the CRT is a monochrome monitor (mode 7). NULL Sx The NULL condition tests the given string and is true if the string is blank or null. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 47 V. Script Language Commands (continued) -> IF <condition> (continued) NUMERIC Sx The NUMERIC condition tests the first char- acter of the given string. It is true if it finds one of the characters 0-9. PRINTER The PRINTER condition tests for the printer enabled through COM-AND (PRINTER ON!OFF). OVERLAY The OVERLAY condition tests for the presence of a machine language overlay file. RECEIVE The RECEIVE condition tests for characters pending on the comm port. It is true if one or more characters are ready to be read. SPECIAL Sx The SPECIAL condition tests the first char- acter of the given string. It is true if the character is not alpha, numeric or control. STRCMP Sx Sy The STRCMP condition is actually a STRCMP performed within the IF statement. The syntax and function are identical to the instruction. -> SUCCESS The SUCCESS condition is set and reset according to the result of the last GETFILE, SENDFILE, ISFILE, RGET, DOS, RUN, LOG OPEN, FFIRST, FNEXT, FDATE, FTIME, FSIZE, FATTR, RENAME, REWIND, DELETE and DIAL statements. TRACE The TRACE condition tests the TRACE ON!OFF status. -> WAITFOR The WAITFOR condition is set and reset by the last WAITFOR statement. XOFF The XOFF condition tests to determine if an XOFF received from the host is currently pending. SOFT flow control must be ON for this test. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 48 V. Script Language Commands (continued) -> IF <condition> (continued) -> ZERO Nx The ZERO condition must be qualified by a numeric value/variable. The condition is true if the evaluation is 0. Note: Expressions may be used in place of Nx, if the expression is parentheticized. For example: "IF ZERO (N0-10)" is allowed. -> <cc> Nx Ny Numeric conditionals are expressed as <cc> (where <cc> may be EQ, LT, GT, LE, GE, NE) followed by two numeric values/variables. IF LT N1 N2 is interpreted: IF N1 LT N2. Note: "NE" is not ASPECT/PROCOMM compatible. Note: An expressions may be used in place of Nx or Ny, if the expression is parentheticized. For example: "IF GT (N0-5) 25" is allowed. Nx <cc> Ny COM-AND allows the normal comparison form to be used, as well. However, as conditional evalua- tion allows parentheses, the first numeric ex- pression DOES NOT allow parentheses. Opening parens of a conditional expression are taken to apply to the conditional, not the numeric. For example: IF (N10-2) eq 5 ; Always fails IF N10-2 eq 5 ; Is fine IF (N10-2 eq 5) ; Is fine, too [Discussion continues on the next page.] Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 49 V. Script Language Commands (continued) -> IF <condition> (continued) IF conditions may be joined with AND, OR, and XOR within one IF statement. Parentheticization is also supported. For example, the statement: IF NOT (FLAG(0) or FLAG(1)) and FLAG(2) ... -> ENDIF AND's FLAG(2) with the negated result of an OR between FLAG(0) and FLAG(1). All clauses are evaluated before the IF is per- formed. In simpler words, FLAG(2) must be "on", AND both FLAG(1) and FLAG(0) must be "off". In the above example, the NOT applies to the result of the parenthetical "(FLAG(0) or FLAG(1))". When NOT precedes a condition without parentheses it applies ONLY to that condi- tion. For example the two fragments below are equivalent: IF NOT FLAG(0) and FLAG(1) = IF NOT FLAG(0) ... = IF FLAG(1) -> ENDIF = ... = ENDIF = ENDIF -> INC Nx The INC command performs the instruction: Nx = Nx+1. No error checking is performed; should the value exceed the range of a numeric variable, results are unpredictable. Example: -> INC N1 ; N1 = N1+1 -> INIT Nx <number> The INIT statement assigns a value to a numeric variable just as ASSIGN assigns a value to a string variable. Example: -> INIT N5 5 ; Initialize N5 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 50 V. Script Language Commands (continued) INPUT Nx <address> The INPUT statement performs a machine level INPUT instruction using the address given. WARNING: If you're not sure what a 'machine level INPUT instruction' is... do not use this! INPUT N0 0x61 ; Read the speaker driver chip ISDLFILE <string> The ISDLFILE statement tests for the presence of a file named in <string> in the current download directory (see SET DLDIR). <String> must contain an unqualified file.ext, (it should not contain a fully pathed file name). ISDLFILE sets the SUCCESS condition according to the presence of the named file. Example: ISDLFILE "COM-AND.EXE" ; Is this file in download dir? Note that ISDLFILE may also be used with IF as the condi- tional test (e.g. IF ISDLFILE S0 ...). -> ISFILE <string> The ISFILE statement tests for the presence of a file named in <string>. <String> contains an unqualified file.ext (or may contain a fully pathed file name). ISFILE sets the SUCCESS condition according to the presence of the named file. Example: -> ISFILE "COM-AND.EXE" ; Is this file in current dir? ISFILE "D:\COM-AND\COM-AND.EXE" Note that ISFILE may also be used with IF as the condi- tional test (e.g. IF ISFILE S0 ...). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 51 V. Script Language Commands (continued) ISSCFILE <string> The ISSCFILE statement tests for the presence of a potential script file named in <string> in the current directory and in the drive:subdirectory specified through the COM-AND= environ- ment variable. <String> must contain an unqualified file.ext, (or may contain a fully pathed file name). The SUCCESS condition is set according to the presence of the named file. Example: ISSCFILE "STCLOGON' ; Is this file available? Note that ISSCFILE may also be used with IF as the condi- tional test (e.g. IF ISSCFILE S0 ...). -> ITOA Nx Sx The ITOA statement converts a value in a numeric variable to a string variable. The value is left justified, with leading zeroes suppressed. Example: N0 = 0 ; N0 now contains 0 -> ITOA N0 S1 ; S1 now contains "0" ITOC Nx Sx[(#)] The ITOC statement converts a value to a single character (for non-ASCII values). Only a single character is deposited, the low 8 bits of the value. Example: N0 = 1 ; N0 now contains 1 (which is SOH) ITOC N0 S1 ; S1(0:0) now contains SOH Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 52 V. Script Language Commands (continued) -> KEYGET Sx The KEYGET statement waits for and reads a single keystroke. The returned string is formatted so that the various possible keys are distinguishable. Printable ASCII keystrokes return one character in Sx. Non-printable ASCII keystrokes (e.g. ESC) are returned as two hex digits (e.g. ESC returns "1B"). Special keys (function and cursor keys) are returned as four hex digits, the last two being '00'. For example, the F1 key is returned as "3B00". Example: -> KEYGET S3 ; Read one keystroke -> KFLUSH The KFLUSH statement flushes the keyboard of keystrokes. It is intended for conditions where type-ahead is not appropriate (e.g. under error conditions). Example: -> KFLUSH ; Throw away key entry LD Sx <number> The LD command returns a long distance string from the dialing directory (or blanks). A directory number may be specified (0,1,2,3,4 are allowed, 1="+",2="-",3="#",4="@", and 0 is a place holder). Note the number field is not optional. Example: LD S0 1 ; Fetch the "+" string LEGEND <string> The LEGEND statement places the given text into the status line on the 25th line of the screen. If <string> is blank, the status line reverts to COM-AND status line notes during script processing. Example: LEGEND "Scripted host mode in effect: Press ESC to abort" Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 53 V. Script Language Commands (continued) LENGTH Sx Nx The LENGTH statement computes the current length of the string Sx (1,2,3...80) and places length in the numeric variable Nx. Example: S0 = " " ; Set-up a value LENGTH S0 N0 ; N0 should now contain 3 Note that lengths range from 0 through 80, while character positions range from 0 through 79. LJ Sx The LJ command left justifies the contents of the given string variable (within its actual length). Example: LJ S0 ; Left justify LOAD (DIAL!MACR!ACCE!DEFA!ALLOC) <fname for DIAL/MACR/ACCE/ALLOC> The LOAD command loads a settings file (either the dialing directory, macro definition, accessory definition, defaults, or allocated variables). Note that 'LOAD DIAL "name"' is equivalent to 'DLOAD "name"'. MLOAD, ALOAD and RESET are similarly redefined. Example: LOAD DIAL "com-and.dir" ; Load original dial dir LOAD DEFAULT ; Note: takes no file name -> LOCATE <number> <number> The LOCATE statement positions the cursor to the row and optionally the column specified by the arguments. The first argument is the row number (0-24, or 0-42). The second number is the column number (0-79). Note that a column argument requires a row argument. Example: -> LOCATE 0,0 ; Position to home (upper left) Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 54 V. Script Language Commands (continued) -> LOG OPEN <string> -> LOG CLOSE -> LOG SUSPEND -> LOG RESUME LOG MARKED (ON!OFF) The LOG subcommands OPEN a file for logging, CLOSE an open LOG file, SUSPEND logging, RESUME logging after suspension, and turn timestamp MARKing in the log on/off. The LOG OPEN command requires a file name in <string>. <String> contains an unqualified file.ext (or may contain a fully pathed file name, not PROCOMM compatible). Example: -> LOG OPEN "Log.txt" ; Open log file and start logging LOG OPEN "E:log.txt" ; OPen log on RAM drive LOG OPEN sets the SUCCESS/FAILURE condition (tested with the IF statement). LOWER Sx The LOWER statement lower cases all alphabetic characters in Sx. Example: LOWER S5 ; Force all lower case -> MACRO <number> [Sx] The MACRO statement will (1) transmit macro number 0-9 from the currently open Macro Definition file (Alt-M) or (2) deposit the macro string 0-9 into a string variable. Example: -> MACRO 8 ; Send macro #8, which winks MACRO 8 S0 ; Read macro #8 into a string variable Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 55 V. Script Language Commands (continued) -> MANUAL <number> The MANUAL statement invokes an interactive window (i.e. as if in CRT mode, in response to an Alt'd Key). The number operand is the scan code equivalent of the Alt'd or Function key that would invoke the window in interactive mode. For example: MANUAL 0x2000 ; Invoke Alt-D The interactive window is terminated with ESCape (in all cases except Alt-F10). The script author is refered to a list of extended keycodes for the operand. Simply, however: ALT Q,W,E,R,T,Y,U,I,O,P -> 0x10 through 0x19 ALT A,S,D,F,G,H,J,K,L -> 0x1E through 0x26 ALT Z,X,C,V,B,N,M -> 0x2C through 0x32 F1 through F10 -> 0x3B through 0x44 ALT 1,2,3,4,5,6,7,8,9,0,-,= -> 0x78 through 0x83 PgUp, PgDn -> 0x49, 0x51 These values make the first two digits of the hex equivalent. The second two digits are always '00'. -> MATGET row col attr len Sx The MATGET statement performs the MGET function, i.e. reading the keyboard for a length with masked echo, with cursor positioning and color control. Example: -> MATGET 0 0 15 5 S5 ; Read up to 5 chars into S5 from 0,0 MATGET 0 0 (black white) 5 S5 Note that the cursor is left positioned after the last character read. -> MDIAL <string> The MDIAL statement dials the number in <string> manually. The value in <string> must be a valid (to the modem) telephone num- ber, and is limited to 14 characters width. Example: -> MDIAL "245-9110" ; Dial P/Link direct Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 56 V. Script Language Commands (continued) MDIR <string> The MDIR statement creates a subdirectory specified as drive: path in the string operand. MDIR performs exactly as the DOS MD command, succeeding and failing in exactly the same cases. MDIR sets SUCCESS or FAILURE according to the result. Example: MDIR "A:\TEMP" ; Create a temp subdir -> MESSAGE <string> The MESSAGE statement displays a line of text on the local console. If logging is enabled, the text is logged as well. Control characters (such as ^G, bell) are embedded in the usual manner. No carriage return/line feed is issued with the <string> unless contained in <string>. Example: -> MESSAGE "^GDialing the SOURCE^M" -> MGET Sx <number> The MGET statement works exactly as the GET statement, taking text from the keyboard (up to a carriage return or <number> length). However, the echo is 'masked'. Asterisks are echoed in place of the entry. Example: -> SET DUPLEX HALF ; Turn off local echo -> MESSAGE "^MEnter a password:" -> MGET S0 15 ; Get up to 15 characters -> TRANSMIT S0 ; Transmit the entry -> TRANSMIT "^M" ; And a cr to terminate -> SET DUPLEX FULL ; Turn echo back on -> MLOAD <string> The MLOAD statement loads a new Macro Definition file (Alt-M). The MLOAD command requires a file name in <string>. <String> contains an unqualified file.ext (or may contain a fully pathed file name). Example: -> MLOAD "COM-AND.MAC" ; Load original macro def MLOAD "C:\SOURCE\COM-AND.MAC" ; Load special macros Note: The file name is limited to 27 characters in length. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 57 V. Script Language Commands (continued) MSR Nx The MSR command reads the modem status register and returns the 8 bit value in a numeric register. The format of the MSR will not be detailed here (refer to your modem's documentation). Example: MSR N0 ; Read the MSR -> MUL Nx Ny Nz The MUL command performs the instruction: Nz = Nx*Ny. No error checking is performed; should the value exceed the range of a numeric variable, results are unpredictable. Example: -> MUL N1 N2 N3 ; N3 = N1*N2 An expression may be used for Nx or Ny if it is entirely contained within parentheses. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 58 V. Script Language Commands (continued) Nx = <expression> Numeric expressions may be computed and assigned directly with the syntax "Nx = <expression>". <Expression> is any legitimate algebraic statement. For example: N0 = N1*(N2+N3) N0 = N5 = N1*(N2+N3) Values may be literal or numeric variables. Operators are: "+", (addition), "-", (subtraction), "/", (division), "*", (multiplication), "\", (returns the remainder of division), "=" (store partial result) "~" (bitwise complement), "&" (bitwise AND), "|" (bitwise OR), "^" (bitwise XOR), Parentheses may be used to clarify ambiguous expressions (unless parentheses are used, the expression is evaluated from left to right), with the following precedences: "(",")" highest precedence "~", "&", "|", "^" second precedence "*", "/" and "\" third precedence "+" and "-" fourth precedence "=" lowest precedence Numeric variables may also be 'indexed'. For example, N0[1] is N1, N1[1] is N2, and so on. Arithmetic expressions are allowed as indices. Indices may be used on either side of a store (e.g. "N0[N1] = N2[N3]"). An index does not 'wrap' (i.e. N0[-1] is N0, not N99). Strings and substrings may be used if they contain valid numeric values. A zero is used (and the ERROR flag is not set) if a string does not contain a valid numeric value. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 59 V. Script Language Commands (continued) OUTPUT <address> Nx The OUTPUT statement performs a machine level OUTPUT instruction using the address given. WARNING: If you're not sure what a 'machine level OUTPUT instruction' is... do not use this! OUTPUT N0 0x61 ; Write the speaker driver chip ON ESCAPE GOSUB <label> The ON ESCAPE GOSUB statement specifies special action to be taken when the operator presses the ESC key. If this is not set, the operator is prompted "Do you wish to terminate the script?". The script writer may choose to intercept the ESC key with a subroutine for the special action. Example: ON ESCAPE GOSUB ESCAPE ; Subroutine label had best exist! Like the GOSUB statement, the operand of this statement may be a literal label, a quoted label, or a string variable containing the label as text. Note: Giving the label as blank is equivalent to the statement ON ESCAPE CLEAR, below. The ON ESCAPE label may be read (using the "_ONEScape" intrinsic), changed, and later reset to its previous condition, using this fact. Note: WOPEN provides its OWN escape handler. When WCLOSE is executed, the ON ESCAPE label previously holding is replaced. Therefore, ON ESCAPE used during a WOPEN sequence will have NO effect outside of the sequence. Note: Although the ON ESCAPE label is NOT cleared upon FCALL, on FRETURN, the ON ESCAPE label holding at FCALL is replaced. Therefore, ON ESCAPE used during a FCALL will have NO effect outside of the FCALLed file. ON ESCAPE CLEAR The ON ESCAPE CLEAR statement clears a previous ON ESCAPE GOSUB setting. After this statement, pressing the ESC key will result in the COM-AND prompt "Do you wish to terminate the script?". Example: ON ESCAPE CLEAR ; Return to default condition Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 60 V. Script Language Commands (continued) ON SILENCE GOSUB <label> The ON SILENCE GOSUB statement specifies special action to be taken after a <duration> of silence on the comm line. The <duration> defaults to 300 seconds (5 min), and may be set with the SET SILENCE command. ON SILENCE GOSUB Disconn ; Subroutine label had best exist! Like the GOSUB statement, the operand of this statement may be a literal label, a quoted label, or a string variable containing the label as text. Note: The script must allow the comm port to be read... with one of the following: RGET, or PAUSE. Note that SUSPEND super- cedes the ON SILENCE condition. Note: When the GOSUB is executed, the ON SILENCE trap is turned off. If it is to be used again, a new ON SILENCE GOSUB must be performed (best in the subroutine itself). Note: The ON SILENCE command 'primes' the timer. Therefore, a loop containing ON SILENCE... will never timeout! The timer will be continuously reset. ON SILENCE CLEAR The ON SILENCE CLEAR statement clears a previous ON SILENCE setting. After this statement, the comm port is not tested for silence. Example: ON SILENCE CLEAR ; Return to default condition OVERLAY <file name> ; Load a file for use OVERLAY CLEAR ; Clear a loaded file The OVERLAY statement loads an EXE or COM format file as machine language subroutines for COM-AND scripts. Routines are invoked in the overlay with the SCALL statement. Example: OVERLAY "talker.ovl" ; Load voice synth routines The OVERLAY statement sets SUCCESS/FAIL according to the result of the attempt. Refer to Appendix K for more discussion. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 61 V. Script Language Commands (continued) -> PAUSE [<number>] The PAUSE statement pauses the script file for a given number of seconds. The delay period defaults to 60 seconds, but may be explicitly set with the numeric argument. Text received during the PAUSE period is displayed on the CRT, and analyzed for WHEN triggers. Example: -> PAUSE 300 ; Pause for 5 minutes PERFORM <string> The PERFORM statement executes the given string as a command. Self modifying code is not recommended, but remote control of COM-AND is easily implemented with this command. Example: S0 = "EXIT" ; Place a command in S0 PERFORM S0 ; Execute S0 as a command PLAY <string> The PLAY statement plays the BASIC encoded music statement in <string>. The ERROR condition is set if the string cannot be parsed (and is therefore not sounded). Refer to the appendices for the syntax of the play statement. Example: PLAY "t220 l8 edcdeee2 ddd2 egg2 edcdeee2 ed.d8edc1" PRESERVE Sx When a value is received (either RGET, GET or MGET), it may contain '!'s and '^'s that would be interpreted as special characters ('!' = carriage return, and '^' = control). The PRESERVE command, applied to a received string variable will modify the value so that a subsequent TRANSMIT or MESSAGE command sends exactly what was received. Example: SET RDISPLAY OFF ; Turn off display of rec'd characters -> RGET S9 ; Read the comm line -> IF SUCCESS ; If not a timeout PRESERVE S9 ; Modify to preserve values -> MESSAGE S9 ; Display on console -> MESSAGE "^M" ; And a carriage rtn -> ENDIF Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 62 V. Script Language Commands (continued) PRINT <string> The PRIN command sends the <string> to the LP1 logging device. The usual string edits are performed first; however, unlike MESSAGE, no line advance is performed first. The PRINT command ignores the setting of the PRINTER ON!OFF (Ctl-PrtSc) state; it prints regardless. Printer error aborts the line, but the next PRINT command is not disabled. Example: PRINT "^L" ; Send a top-of-form -> PRINTER (ON!OFF) The PRINTER command turns on and off the local LP1 logging of received (and echoed) text. -> QUIT The QUIT command terminates the script execution and COM-AND. It may be coded at any level (for example within a subroutine reached through a call from a subroutine). Example: -> QUIT ; Terminate the script and program ; Nothing past this point in the script will be performed. Note also the BYE command. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 63 V. Script Language Commands (continued) RDIR <string> The RDIR statement removes a subdirectory specified as drive: path in the string operand. RDIR performs exactly as the DOS RD command, succeeding and failing in exactly the same cases. RDIR sets SUCCESS or FAILURE according to the result. Example: RDIR "A:\TEMP" ; Remove a temp subdir READ Sx Nx Ny The READ command reads a string (up to Nx characters) into a string variable. The input file must be opened by FOPENI. READ reads up to 80 characters into Sx. If the input file was opened in TEXT mode, the read string terminates at the 80th byte or at a CR/LF pair (NOT placed in Sx as a single CR). The count read is placed in Ny. Example: READ S0 80 N4 ; Read 80 bytes; count read in N4 In TEXT mode, the READ function terminates when a CR/LF is en- countered. In TEXT mode, tabs are expanded to blanks. In TEXT mode, the READ command stops on an ASCII EOF character (Ctl-Z) as well as on true end-of-file (size). In TEXT mode, when an empty record is encountered (i.e. CR/LF), the returned length is 0 and the returned buffer is empty. When a record longer than 80 characters is encountered, the first READ returns a length of 80 and subsequent READ statement(s) return the remainder of the record. Special note should be made of cases where a length of 80 exactly is returned. Should the next READ return a length of 0, the record was 80 text charac- ters, and the 0 length record represents the record's CR/LF. The READ command sets the EOF condition on input EOF. This may be tested with an 'IF EOF'. On EOF the buffer is returned null. RENAME <oldfile> <newfile> The RENAME statement renames a file named in the command. The SUCCESS flag is set according to the result of the command. Example: RENAME "COM-AND.LOG" "COM-AND.OLD" Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 64 V. Script Language Commands (continued) RESET The RESET statement restores default settings (Alt-S, Alt-O, and Alt-P) to their load-time values. It also restores the default download subdirectory. It does not reset the current subdirec- tory or the scrolling region coordinates. Example: RESET ; Restore default parameters RESTORE The RESTORE statement restores an area saved by the SAVE statement. The coordinates used by the SAVE statement are implicit to the RESTORE statement. The RESTORE statement sets the SUCCESS flag according to save-stack underflow. RESTORE ; Restore saved area -> RETURN The RETURN command transfers control of the script processor to the last GOSUB executed. RETURN effectively cancels the domain of any IF or SWITCH statement being processed. The RETURN may be coded at any level (for example within an IF). Example: -> LABEL: ... -> RETURN ; Return to caller REWIND The REWIND statement rewinds the input file (if open). The SUCCESS flag is set according to the result of the command. Example: REWIND ; REWIND the input file -> RFLUSH The RFLUSH command flushes the receiver buffer of received text. Text being flushed is not displayed at the CRT. Example: -> RFLUSH ; Flush anything left over -> HANGUP ; Disconnect the call Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 65 V. Script Language Commands (continued) -> RGET Sx [<number> [<number>]] The RGET command reads the comm port for text. Received text is terminated by a carriage return (in RMODE ASCII), or, if the optional first numeric argument was supplied, after <number> characters. Receipt may also be terminated after a stated or unstated period of time (default is 60 seconds; the value may be changed with the optional second numeric argument). Example: -> RGET S0 24 300 ; Wait up to 5 mins for 24 characters Note that the delay interval cannot be specified without the first numeric argument (length) also present. Note that if WHEN triggers are to be performed during an RGET, the RGET length must be greater than the largest WHEN trigger string. RGET sets the SUCCESS/FAILURE condition (which may then be tested with the IF statement). RGET will read in either an ASCII or BINARY mode. Its default is ASCII. In ASCII mode, nulls and linefeeds are ignored, carriage returns end the RGET, and backspaces are performed. In binary mode, the RGET is terminated only by length. The RGET mode is set with the SET RMODE statement. RJ Sx The RJ command right justifies the contents of the given string variable (within its actual length). Example: RJ S0 ; Right justify RND <modulus> Nx The RND command computes a random number (smaller than the given modulus value) and places the value in Nx. Example: RND 6 N0 ; Roll one six faced die (n0 = 0 to 5) Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 66 V. Script Language Commands (continued) -> RUN <string> [WAIT] The RUN command executes any executable program that may be loaded 'on top of' COM-AND. The RUN command will not work if there is not sufficient memory to load the new program. Parameters may be passed to the new program by including them after the file name. Example: -> RUN "VCOLIB.EXE" ; Load VCOLIB (menu mode) RUN "VCOLIB.EXE L GENIE.FLB" ; Load and list to CRT The optional keyword WAIT signals that COM-AND is to pause after completion for a keypress before the script continues. This command sets the SUCCESS condition according to the error level returned to DOS by the target program. NOTE: The screen is saved prior to the RUN function, for restoration upon completion. However, the screen size saved is defined by the DWINDOW currently in effect! SAVE row col row col The SAVE statement saves an area of screen on a stack. The first and second arguments specify the row/column of the top-left of the region. The third and fourth arguments specify the row/column of the bottom-right of the region. Up to 20 regions may be saved at one time. The SUCCESS flag is set/reset according to save-stack overflow. Example: SAVE 0 10,10 20,20 ; Save a narrow box. SCALL <addr> [parms [,parms]] The SCALL instruction invokes a procedure in an overlay. The address of the procedure (relative to the first 64K) must be supplied. Optional numeric (nx) and string (Sx, Vx) variables may be listed after the mandatory address. All parameters are passed by reference and may therefore be modified by the over- lay routine. For example: SCALL 3 N0 ; Invoke proc at addr 3, pass/rtn N0 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 67 V. Script Language Commands (continued) SCREEN row col row col attr Sx The SCREEN statement provides for a multi-line display within an area on the screen. The leftmost column and the number of lines to be be displayed are defined by the box coordinates. The color attribute is used on each line displayed. Lines are displayed string with the string variable given, and proceeding in sequence. For example: SCREEN 10,10 20,20 (black white) S0 displays 11 lines from variables S0 through S10. Note that the given attribute ONLY applies to text written (not the whole box) and that the box width does NOT limit the line length displayed. -> SCROLL cnt row col row col attr The SCROLL statement scrolls a region on the screen, filling the new lines with the specified color. The first argument <cnt> specifies the number of lines to scroll (0 implies that the region is to be cleared). The second and third arguments specify the row/column of the top-left of the region. The fourth and fifth arguments specify the row/column of the bottom-right of the region. The last argument specifies the color attribute to be used on the new line. Example: -> SCROLL 0 10,10 20,20 15 ; White on black: narrow box SCROLL 0 10,10 20,20 (black white) Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 68 V. Script Language Commands (continued) -> SENDFILE ASCII <string> ; A.K.A. Buffer capture -> SENDFILE BYMODEM <string> ; Batch YMODEM -> SENDFILE BYMODEMG <string> ; Batch YMODEM-G (BYMOG works too) -> SENDFILE CISB ; CompuServe B-protocol -> SENDFILE KERMIT <string> ; Kermit or SuperKermit SENDFILE QUICKB ; CompuServe Quick B-protocol -> SENDFILE RXMODEM <string> ; Relaxed CRC or Checksum XMODEM -> SENDFILE WXMODEM <string> ; Windowed XMODEM -> SENDFILE XMODEM <string> ; CRC or Checksum XMODEM -> SENDFILE YMODEM <string> ; Simple YMODEM (not True ... (TM)) SENDFILE ZMODEM <string> ; ZMODEM transfer (batch) The SENDFILE statement initiates an upload using a specific protocol. The <string> argument must specify a valid file name, and the file must exist. The SENDFILE command sets the SUCCESS condition according to the transfer. Example: -> SENDFILE XMODEM "Com-and.arc" ; Upload Note that, in the case of CISB and QUICKB, you tell the host the name the file will take on your machine. Note that CIS-B ( and QuickB) provide an automated upload function. The automated function is NOT available within a script unless the script is 'reading the port', i.e. with an RGET, PAUSE or SUSPEND statement. -> SET <command...> The SET commands are discussed below in a chapter alone. -> SHELL The SHELL command shell's to DOS using COMMAND.COM or the command line interpretor indicated by the 'COMSPEC=' envi- ronment variable. Having shelled to DOS, DOS commands may be executed... however, the shell must be exited for the script to continue. COMMAND.COM is exited with the command "Exit". Example: -> SHELL ; shell to DOS NOTE: The screen is saved prior to the SHELL function, for restoration upon completion. However, the screen size saved is defined by the DWINDOW currently in effect! Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 69 V. Script Language Commands (continued) SNAME Sx The SNAME command returns the current script file name in the variable given. Example: SNAME S0 ; shell to DOS This function is provided to make it possible for a script that has been 'EXECUTE'd from another script file to return to the original script. Note that when a script is started, all string variables are set to blank. When a script is 'EXECUTE'd string variables retain their current values. -> SOUND <number> <number> The SOUND statement generates a sound of a specific frequency for a duration specified in milliseconds. The first argument is the frequency (in Hz). The second argument is duration. Both may be specified as literal values or as variables. Example: -> SOUND 440 500 ; Sound a 'A' for half-a-sec SSIZE Nx The SSIZE statement returns the current # of screen lines in the given numeric variable. Example: SSIZE N0 ; Compute # screen lines Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 70 V. Script Language Commands (continued) STACK <string> STACK CLEAR The STACK statement stores the given string (if there is room) in the BIOS keyboard buffer. STACK CLEAR clears the BIOS keyboard buffer. STACK may be used prior to BYE to effect a chain to another program. For example: STACK "PC-VCO!" ; Stack cmd to load PC-VCO -> BYE ; Exit COM-AND without hanging up Note that STACK, like HITKEY, sets a state inhibiting type- through until the next KEYGET/GET/MGET/ATGET/MATGET/KFLUSH. To STACK a non-ASCII key, preceded the 'extended code' with null (^@). Please refer to Appendix H of this document for a table of extended keycodes as used by the STACK command. Note that the STACK command uses the EBL keyboard stack, if EBL is available. Refer to Appendix (F) below covering EBL for information on EBL. The BIOS keyboard buffer is limited to 15 characters. The EBL provides a larger buffer for STACK's use. [Note that various utilities and TSRs may provide a larger keyboard buffer. If so, COM-AND will use the larger buffer.] STORE (DIAL!MACR!ACCE!DEFA!ALLOC) [parms] The STORE command writes a settings file (either the dialing directory, macro definition, accessory definition, defaults, or allocated variables). Note that 'STORE DEFAULTS' is equivalent to 'UPDATE'. Example: STORE DIAL ; Update original dial dir STORE DEFAULT ; Note: takes no file name The only STORE subcommand taking a parameter is STORE ALLOCATED. The other statements store to the file currently in use. STORE ALLOCATED (storing allocated variables to a disk file) requires a specific file name for the store. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 71 V. Script Language Commands (continued) -> STRCAT Sx Sy The STRCAT statement concatenates two strings, Sy onto Sx. The concatenation occurs after the last character of Sx. Example: -> STRCAT S0 S1 ; Concat S1 onto S0 STRCAT S0 S1(5:10) ; Extract substring of S1 and add Note that the command above is equivalent to the following: CONCAT S0 * S1 ; Another way to say this -> STRCMP Sx Sy The STRCMP statement compares two strings (case sensitive) and sets the SUCCESS flag if they are identical. Example: -> STRCMP S0 S1 ; Compare strings in S0 & S1 -> IF SUCCESS ; IF they are equal... ... ; ... Note that STRCMP may also be used with IF as the conditional test (e.g. IF STRCMP S0 S1 ...). -> STRCPY Sx <string> The STRCPY statement assigns the value in <string> to Sx. It is equivalent to the ASSIGN statement. Example: -> STRCPY S0 S1 ; S0 = S1, or ASSIGN S0 S1 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 72 V. Script Language Commands (continued) -> STRFMT Sx <fmtstr> <parms> The STRFMT statement formats variables (and literals) into a template and places the result into a string variable. The argument <fmtstr> above is the formatting template. The argument list <parms> above is a list of variable names (and literals and substrings) to be formatted. Example: -> STRFMT S0 "The answer is %d %s" N1 S1 In the above example, the value in N1 replaces %d and the text in S1 replaces %s. Format specifiers in the template have the form: %[<flags>][<width>][.<precision>]<type> <Flags> are "-" meaning left justify the argument and "+" meaning display the argument with a plus or minus sign (if numeric). The defaults are right justified and signed only if negative. <width> specifies the minimum number of characters to be displayed. If <width> is greater than the value, blanks are added to the left or right (according to the justification). If <width> is prefixed by 0, 0's are used in place of blanks. .<precision> specifies the minimum number of digits to be displayed. 0's are added to the left of the formatted value to achieve <precision>. <type> "d" specifies decimal numeric values (signed) "u" specifies unsigned decimal values "x" specifies hex values "s" specifies string values The <fmtstr> is scanned from left to right for format specifiers. As specifiers are found, parameters after <fmtstr> are extracted and used sequentially. This usage is similar to the Microsoft "C" compiler's usage. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 73 V. Script Language Commands (continued) -> SUB Nx Ny Nz The SUB command performs the instruction: Nz = Nx-Ny. No error check is performed; should the value exceed the range of a numeric variable, results are unpredictable. Example: -> SUB N1 N2 N3 ; N3 = N1-N2 An expression may be used for Nx or Ny if it is entirely contained within parentheses. SUBDIR Sx The SUBDIR statement stores the current default drive:sub- directory into the target variable. Example: SUBDIR S0 ; Get current drive:path -> SUBSTR Sx Sy <number> <number> The SUBSTR statement extracts a substring from Sy and places it in Sx. The beginning character position is specified by the first numeric argument (0,1,2...). The second numeric argument specifies the length of the substring. Example: -> SUBSTR S0 S1 5 10 ; S0 = S1 at 5 for 10 Note that the command above is equivalent to the following: S0 = S1(5:14) ; Another way to say this Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 74 V. Script Language Commands (continued) SUSPEND FOR <number> <number> -> SUSPEND UNTIL <number> <number> The SUSPEND FOR statement suspends COM-AND for the duration indicated (in military form). The suspension may be up to 24 hours. The first argument is hours (0-23) and the second argument is minutes. Example: SUSPEND FOR 0 30 ; Wait a-haffa hour The SUSPEND UNTIL statement suspends COM-AND until the time indicated (in military form). Example: -> SUSPEND UNTIL 4 30 ; 4:30 AM Incoming text received during SUSPEND is displayed on the screen. Keystrokes are transmitted. The SUSPEND may be terminated with the ESC key. WHEN is active during SUSPEND. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 75 V. Script Language Commands (continued) -> SWITCH (Sx!Nx) The SWITCH statement declares a variable to be tested and a domain for transfer of control. A SWITCH statement must be followed an ENDSWITCH statement. Lines between the SWITCH and the ENDSWITCH statements are the domain of the SWITCH function. Within the SWITCH domain, CASE statements test the given variable for a value (not case sensitive). If a match is obtained, the statements following the CASE statement are executed until an ENDCASE is encountered. A DEFAULT statement specifies a clause to be executed if none of the prior CASEs have been executed. The DEFAULT clause is terminated by an ENDCASE; just as a CASE statement. Schematically: -> SWITCH (Sx!Nx) ; Set variable to be tested. CASE (<string>!<number>) ; Match Sx and <string> ... ; .. execute if a match -> ENDCASE ; End of first case -> CASE <string> ; <String> = "_NULL" -> empty ... -> ENDCASE ; End of second case ... -> DEFAULT ; DEFAULT executed if no case ... ; .. was matched -> ENDCASE ; End of default case -> ENDSWITCH ; End of SWITCH domain Statements between a SWITCH and an ENDSWITCH which are not themselves within a CASE/ENDCASE or DEFAULT/ENDCASE are ignored. SWITCH domains may be nested with IF domains, GOSUBs, DO, FOR and WHILE up to a maximum stack depth of 20. Note that either a string OR a numeric variable may be used with the SWITCH statement. Strings and numerics may be mixed in any (useful) manner with SWITCH and CASEs. Substring bounds are not allowed on the SWITCH variable, but are allowed on the CASE variable. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 76 V. Script Language Commands (continued) Sx = <expression> String expressions may be computed and assigned directly with the syntax "Sx = <expression>". <Expression> is any legitimate combination of values and operators. For example: S0 = S1 & S2 * S3(4:5) S0(70:79) = S1 Values may be literal or string/numeric variables. Operators allowed are "*" (concatenate at end), and "&" (trim trailing blanks and then concatenate). Substrings may be specified using (from:to) notation: from column # to column #. Numeric variables may also be included. An implicit ITOA will be performed (leading zeroes suppressed and left justified). The width of the value is exactly the width of the value so formatted. This usage, string expression, is the only statement in the COM-AND script language that supports 'string deposit'... i.e. specification of a substring for assignment. I hope that a future extension of this script language will allow string deposit as freely as string extraction. String variables may also be 'indexed'. For example, S0[1] is S1, S1[1] is S2, and so on. Arithmetic expressions are allowed as indices. Indices may be used on either side of a store (e.g. "N0[N1] = N2[N3]"). An index does not 'wrap' (i.e. N0[-1] is N0, not N99). For example: S0 = S0[2](2:3) ; Extract cols 2-3 from S2 and place in S0 -> TERMINAL The TERMINAL statement terminates a COM-AND script, returning to CRT mode. It may be coded at any level (for example within a subroutine reached through a call from a subroutine). Example: -> TERMINAL ; End of script ; Nothing past this point in the script is executed Note also the EXIT and CONNECT command. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 77 V. Script Language Commands (continued) -> TIME Sx [0!1] The TIME statement store the current system time into the target variable. The TIME is formatted according to the optional format argument (if provided and nonzero, the time is formatted hh:mm:ss where hh is 0-23; otherwise it is formatted hh:mm:ss with a final AM or PM). Example: -> TIME S1 1 ; Get the time of day military fmt -> TRACE (ON!OFF) The TRACE statement turns on and off script file tracing. When tracing is enabled, each line of the script file is displayed on the CRT before the statement is executed. If logging is enabled, the trace display is also copied to the log. Example: -> TRACE ON ; Turn on tracing -> TRANSMIT <string> The TRANSMIT statement writes the given string to the commun- ications line. TRANSMIT does not add a carriage return to the string; if a carriage return is required, it should be contained in the string (^M is a carriage return). TRANSMIT backscans the text to be transmitted and does not send trailing blanks. Examples: -> TRANSMIT S0 ; Send what's in S0 -> TRANSMIT "text" ; Send text without a c/r -> TRANSMIT "text^M" ; Send text with a c/r Note: To be compatible with PCPlus, a tilde (~) represents a 1/2 second pause in the TRANSMIT string. TSINCE [(#)] Nx Ny Nz The TSINCE statement reads the time since a given timer was set (all timers are initialized to the time the script is loaded but may be changed with "SET TIMER"), in hours, minutes and seconds. 10 timers are supported. Example: TSINCE N0,N1,N2 ; Read time since timer 0 was set TSINCE (9) N0,N1,N2 ; Read time since timer 9 was set Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 78 V. Script Language Commands (continued) -> TYPE <string> The TYPE statement opens the file specified by <string> and displays it to the local console. This is equivalent to the interactive Alt-W command of COM-AND. Example: -> TYPE "COM-AND.DOC" ; Don't do this: too big! UNTIL <condition> The UNTIL statement terminates the clause of a DO loop. The specified condition is evaluated, and looping occurs if the evaluation is false. Refer to DO above for an example. The <condition> executed by UNTIL has the same form as the condition of the 'IF' statement. UPDATE The UPDATE statement updates the .DFT file. This is equivalent to the STORE DEFAULT instruction. Example: UPDATE ; Store new settings UPPER Sx The UPPER statement upper cases all alphabetic characters in Sx. Example: UPPER S5 ; Force all upper case VERSION Nx The VERSION statement reads the current version of COM-AND (major*10+minor) and places it into a numeric variable. Example: VERSION N0 ; N0 = 23 if version 2.3 Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 79 V. Script Language Commands (continued) -> WAITFOR <string> [<number>] The WAITFOR instruction waits up to given (explicit in <number>, or default) number of seconds for a the target string to be received. The WAITFOR instruction sets the WAITFOR condition (tested by IF) according to whether or not the target <string> was received. The WAITFOR function is not case sensitive. Example: -> WAITFOR "U#=" ; Waitfor GEnie user # prompt Note: As with WHEN strings, carriage returns, line feeds, and backspaces should not be encoded in the WAITFOR target. A special provision has been made for the construct: -> WAITFOR "^M" ; Waitfor the next carriage return This was required because of the frequency with which scripts that have been published use the construct. However, in the general case, avoid carriage returns, line feeds and back- spaces in the WAITFOR string. WCLOSE The WCLOSE instruction closes a window opened with the WOPEN instruction. If no windows are open FAILURE is set. Otherwise, (1) The saved area (if one was saved) is restored and (2) The ON ESCAPE condition at the time of the WOPEN is restored. Example: WCLOSE ; Must match a WOPEN above Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 80 V. Script Language Commands (continued) -> WHEN [(#)] <string> <string> The WHEN instruction establishes a 'trigger' condition which will be recognized and responded to automatically. WHEN has two arguments: the first argument is a <string> which, when received will result in the transmission of the second string. Example: -> WHEN "Press return for more" "^M" ; Respond w/c/r The WHEN statement has been extended to allow up to 10 WHEN settings (WHEN (0), WHEN (1) ... WHEN (9), with an unqual- ified WHEN equivalent to WHEN (0)). Each must be set and cleared individually. Examples: WHEN (0) "more?" "^M" ; Same as WHEN WHEN (9) "Agree?" "Y^M" ; Set last WHEN WHEN trigger strings are not case sensitive; you needn't represent the trigger exactly. The WHEN matching begins after receipt of a carriage return, and continues until the length buffered exceeds that of the WHEN string. Note: The SET ANYWHEN statement affects the type of match performed by the WHEN statement. When ANYWHEN is off (the default), a match must be made from the start a received line (i.e. immediately after the return). When ANYWHEN is on, the match is a substring test against the entire received buffer. If WHEN triggers are to be used during an RGET, the length of the RGET target must be larger than the largest WHEN trigger string. Carriage returns and line feeds cannot be included in a WHEN trigger string. WHEN settings are cleared with the CWHEN statement. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 81 V. Script Language Commands (continued) WHILE <condition> The WHILE statement asserts the beginning of a loop, if the condition specified evaluates true. The clause after the WHILE statement is executed through an ENDWHILE statement and looping occurs (back to evaluate the condition again). The WHILE statement evaluates the given condition (see the 'IF' statement for a list of conditions). If the evaluation is false, statements following are skipped until the corresponding ENDWHILE is encountered. Example: N0 = 0 ; Initialize index WHILE LT N0 10 ; Loop for 10 times N0 = N0+1 ; Increment index ... ENDWHILE ; Loop back to WHILE Note: (1) GOTO statements may never enter a WHILE loop; even to leave an inner loop to return to an outer loop. Note: (2) WHILE statements may be nested (along with IF, FOR, WHILE, SWITCH and DO loops) up to 20 levels. How- ever, they may not overlap other WHILE loops, or other flow-of-control statements. Note: (3) The clause of the WHILE statement (statements after 'WHILE' down to the ENDWHILE statement) is not necessarily executed, even once. The conditional evaluation is performed before each iteration. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 82 V. Script Language Commands (continued) WOPEN row col row col attr [label] The WOPEN command opens a window on the screen, saving the current ON ESCAPE setting, and optionally, setting a new ON ESCAPE condition. Up to 10 windows may be opened at one time (if 10 is exceeded, FAILURE is set). The WOPEN instruction combines a number of other instructions into a one function. WOPEN is equivalent to: Sx = "_ONESCAPE" ; Read current ON ESCAPE GOSUB label ; Set new CURSOR Nx Ny ; Read current & save SAVE row col row col ; Save screen area -> BOX row col row col attr ; Clear scr, draw box The corresponding WCLOSE is equivalent to: ON ESCAPE GOSUB Sx ; Reset condition RESTORE ; Restore screen -> LOCATE Nx Ny ; Restore cursor The ON ESCAPE condition is reset upon WCLOSE to the setting at the time of the WOPEN. Intervening "ON ESCAPE" statements are therefore cancelled. Intervening SAVEs and RESTOREs are not cancelled, however. Have care! Example: WOPEN 10,10 20,70 (default) ESCAPE_Label ; Open a window Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 83 V. Script Language Commands (continued) WRITE Sx [Nx] The WRITE command writes a string from a string variable to the output file. The length of the string variable is specified by Nx. The output file must be opened by a previous FOPENO. In TEXT mode the WRITE command translates CRs in the string buffer to CR/LF pairs. No tab compression is performed. WRITE writes up to 80 characters from Sx, according to the value in Nx. Example: WRITE S0 75 ; Write 75 bytes Note that the length given applies to the string as given. The string "^M" is 2 characters long and should be specified as a length of 2, although only 1 character (control-M) will be written. The string "`"", interestingly enough, is 1 character long! Note that the length parameter is optional. If not specified, the current length of the variable will be computed. Note that COM-AND does not write a ^Z (decimal 26) to the output file when it is closed, having been opened in TEXT mode. The script author may add the ASCII EOF convention by preceding the FCLOSEO with the statement: WRITE "^Z" ; ASCII EOF convention Note also: FPUTC/FPUTS/FWRITE commands. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 84 VI. SET commands SET subcommands allow string variables for their operands. For example, ON or OFF may be contained in a string, and the string used as the final operand of the statement. A. Basic set SET 25 SET 25 turns on CGA mode (25 lines), for CGA/Monochrome. NOTE: SET 25 clears any DWINDOW in effect. SET 43 SET 43 turns on EGA mode (43 lines), if an EGA is available. [SET 43 sets VGA (50 lines), if VGA is available.] NOTE: SET 43 clears any DWINDOW in effect. SET ACCESSORY NAME # <string> SET ACCESSORY SUBD # <string> SET ACCESSORY PGM # <string> SET ACCESSORY SCRI # <string> SET ACCE <field> stores the given string into the stated field (name, subdir, ...). Each field is differently sized. Accessory directory entry numbers range from 1-50. SET ADVERT (ON!OFF) SET ADVERT sets and resets the initial advertisement display. -> SET ALARM (ON!OFF) SET ALARM sets and resets the alarm function. When OFF, the alarm does not sound (e.g. after download),but a delay, for a period set through Alt-S or SET ATIME, is performed. SET ANYWHEN (ON!OFF) SET ANYWHEN controls the execution of any current WHEN condi- tions. When ANYWHEN is off (the default), matching occurs from the beginning of the buffer. When ANYWHEN is on, the match is actually a substring match to the received buffer. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 85 VI. SET Commands (continued) A. Basic set (continued) -> SET ASCII <subcommand> The SET ASCII subcommands are discussed below (section "VI"). -> SET ATIME <number> Alarm time SET ATIME sets the duration (in seconds) of the alarm. -> SET BACKSPACE IN (NONDESTRUC!DESTRUC) SET BACKSPACE IN controls the function performed when a backspace is received. Nondestructive backspaces are not common, but may be needed occasionally. -> SET BACKSPACE OUT (BACKSPACE!DELETE) SET BACKSPACE OUT controls the function performed when a backspace is typed. Either a 'backspace' character (0x8) or a delete character (0x7f) may be transmitted. SET BAR <attr> SET BAR sets the status line bar color. The change takes effect the next time the status line is updated (e.g. with the LEGEND command). The new color holds after the script. -> SET BAUDRATE (300!1200!2400!4800!9600!19K!38K!56K!115K) SET BAUD sets the communications port linespeed. This command results in a reset of the line. SET BELL <number> SET BELL sets the bell tone in hertz. SET BKSCREEN <number> SET BELL sets backscreen size in pages (0-64). Note that this function clears the current backscreen in the process. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 86 VI. SET Commands (continued) A. Basic set (continued) -> SET BREAK <number> SET BREAK sets the duration (in milliseconds) of the break signal (BREAK statement or Ctrl-end). SET BSUPPRESS (ON!OFF) SET BSUPPRESS sets and resets blank line suppression as implemented in COM-AND. SET CALLLOG (ON!OFF) SET CALLLOG sets and resets COM-AND's call logging. The calllog records DIAL (Alt-D), REDIAL (Alt-R), HANGUP (Alt-H), and file transfers (PgUp and PgDn). SET CDISPLAY (ON!OFF) SET CDISPLAY turns on and off control character display. BBS's often use control characters as graphics, and network host systems only generate them inadvertantly. SET CDRESPECT (ON!OFF) SET CDRESPECT sets and resets COM-AND's treatment of the modem carrier detect. When CD respect is 'off', COM-AND treats modem carrier as always 'true'. SET CHAT (ON!OFF) SET CHAT turns on and off chat mode. SET CHLINES <number> SET CHLINES specifies the size of the CHAT window. SET CLOCK (ON!OFF!NEW) SET CLOCK turns on and off the on-screen clock. The "NEW" subcommands resets the "call time" and makes an entry in the calllog (if calllogging). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 87 VI. SET Commands (continued) A. Basic set (continued) SET COLOR (ON!OFF) SET COLOR sets/reset COM-AND's use of a color monitor, if available. Note the screen is repainted accordingly. SET COMBASE <port> Nx SET COMBASE specifies the base address to be used for the given port (COM1, COM2, etc). SET COMVECTOR <port> Nx SET COMVECTOR specifies the vector number to be used for the given port (COM1, COM2, etc). -> SET CR (CR!CR_LF) SET CR controls the display of received carriage returns. When set to CR_LF, received carriage returns are displayed as carriage return/line feeds. -> SET CR_IN (CR!CR_LF) SET CR_IN is equivalent to SET CR above. -> SET DATABITS (7!8) SET DATA sets the communications port to 7 or 8 data bits (this does not affect XMODEM, WXMODEM, or YMODEM transfers). SET DBLCLICK # SET DBLCLICK specifies the interval (in MS) during which a double click of the mouse button may occur. SET DEFAULT <attr> SET DEFA sets the color for menu windows. The change takes effect the next time a window is invoked (e.g. with an alt'd key). The new color holds after the script terminates. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 88 VI. SET Commands (continued) A. Basic set (continued) SET DIAL NAME # <string> SET DIAL NUMB # <string> SET DIAL RATE # <string> SET DIAL PARI # <string> SET DIAL DATA # <string> SET DIAL STOP # <string> SET DIAL SCRI # <string> SET DIAL <field> stores the given string into the stated field (name, number, ...). Each field is differently sized. Dialing directory entry numbers range from 1-100. -> SET DISPLAY (ON!OFF) SET DISPLAY sets and resets the display of received char- acters. You may use this to suppress (OFF) received text while you wait for an appropriate response. -> SET DLDIR <string> SET DLDIR establishes a default path for downloaded files when the file name given is not pathed. The <string> provided may be of the form: d:\path...\path SET DOSLEVEL <number> SET DOSLEVEL establishes an error level (default 0) to be returned to the invoking program when COM-AND terminates. Among other things, this provides a means to exit COM-AND but retain control of processing (via a batch file). SET DPREFIX <string> SET DPREFIX specifies the prefix used to build a dialing command. SET DROPDTR (ON!OFF) SET DROPDTR specifies method used (issue modem escape+hangup string, or drop DTR) to hangup. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 89 VI. SET Commands (continued) A. Basic set (continued) SET DSUFFIX <string> SET DSUFFIX specifies the suffix used to build a dialing command. SET DTR (ON!OFF) SET DTR raises and lowers the DTR signal to the modem. -> SET DUPLEX (HALF!FULL) SET DUPLEX turns on (HALF) and off (FULL) local echo. -> SET ENQ (OFF!CISB) SET ENQ CISB allows automatic file transfers initiated by CIS. SET ENQ OFF ignores ENQ characters. SET EXIT <script name> SET EXIT specifies a script file name to be invoked upon termination of COM-AND. Termination occurs manually with Alt-X, or through the script command BYE. When terminated and an EXIT script has been set, COM-AND invokes the script, after testing for carrier. When an EXIT script is set, the only way to terminate COM-AND is through the script itself. i.e. no EXIT script is specified in the EXIT script, and the EXIT script performs a BYE command. Note that the EXIT script function is cleared when it is invoked... i.e. an EXIT script must re-specify an EXIT script name if the function is to be preserved (and COM-AND not to terminate). Note that COM-AND must be ABLE to find the EXIT script on termination. It is best if all EXIT scripts reside in the COM-AND= environment variable pointed subdirectory. SET EXQUERY (ON!OFF) SET EXQUERY sets/resets the query-on-exit function. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 90 VI. SET Commands (continued) A. Basic set (continued) SET FAILURE (ON!OFF) SET FAILURE sets and resets the FAILURE condition tested by the IF statement. SET FAILURE may be used to modify various conditions setting and resetting SUCCESS/FAILURE. SET FLAG [(#)] (ON!OFF) The SET FLAG instruction sets and resets one of 10 flags. Flags may be tested with the IF statement. -> SET FLOWCTRL (ON!OFF) SET FLOWCTRL turns on and off software flow control used during receipt of text from the host. This command is global (SET ASCII FLOW is local to ASCII SENDs), affecting both display receipt and ASCII sends. SET FOUND (ON!OFF) SET FOUND sets and resets the FOUND condition tested by the IF statement. SET FOUND may be used to imitate FIND statement returns. -> SET HARDFLOW (ON!OFF) SET HARD enables and disables hardware flow control. Flow control is performed at the hardware level by raising RTS and waiting (for up to 20 seconds) for CTS. Note that HARD- FLOW is overridden by RTSFLOW (below). SET HMOUSE # SET HMOUSE specifies the mouse horizontal sensitivity. SET INAFTER (ON!OFF) SET INAFTER turns on and off modem initialization after hangup. SET KBDBUFFER (ON!OFF) SET KBDBUF turns on and off the keyboard display buffer. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 91 VI. SET Commands (continued) A. Basic set (continued) -> SET KERMIT <subcommand> The SET KERMIT subcommands are discussed below ("VI"). SET LD # <string> SET LD stores the given string into the given LD directory entry: 1,2,3, or 4 is required, 1="+",2="-",3="#",4="@" in the Alt-D LD directory. SET LINKED (ON!OFF) SET LINKED sets and resets the LINKED condition tested by the IF statement. SET LINKED may be used to imitate script execution through Alt-D. SET MACRO # <string> SET MACRO stores the given string into the given MACRO dir- ectory entry: 0-9. SET MASK (ON!OFF) SET MASK sets and resets the 7 bit mask of COM-AND. SET MCONNECT <string> SET MCONNECT specifies the modem connect string used to recognize a successful dialing function. SET MDCHAR <value> SET MDCHAR sets an alternate modem delay character used as 1/2 second delays in TRANSMIT and in modem strings. Note that this value is retained after the script terminates. SET MDELAY # SET MDELAY specifies the intercharacter time (in MS) for strings issued to the modem (e.g. dialing strings). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 92 VI. SET Commands (continued) A. Basic set (continued) -> SET MENUMODE (ON!OFF) SET MENUMODE specifies the new MENUMODE value. It takes effect only upon completion of the script. SET MESCAPE <string> SET MESCAPE specifies the string to be used to get the attention of the modem (e.g. before hangup). SET MHANGUP <string> SET MHANGUP specifies the string used (if DROPDTR is OFF) to hangup the phone. SET MINIT <string> SET MINIT specifies the string transmitted to the modem when COM-AND is loaded. SET MUSIC (ON!OFF) SET MUSIC sets and resets COM-AND's processing of music escape sequences. Music escape sequences are received: "ESC [ M <string> <control-N>'. -> SET PARITY (EVEN!ODD!NONE) SET PARITY sets the communications line parity. SET PCJR (ON!OFF) SET PCJr sets and resets a PCJr mode, which suspends the comm line during disk I/O. This only effects transcripts, Windowed XMODEM and Windowed Kermit. -> SET PORT (COM1!COM2!COM3!COM4) SET PORT declares the communications port to be used. This command resets the communications line. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 93 VI. SET Commands (continued) A. Basic set (continued) SET QUIET (ON!OFF) SET QUIET turns on and off bell character suppression. -> SET RDELAY <number> SET RDELAY sets the duration (in seconds) of the delay between Alt-R and script DIAL statement redial attempts. SET RDISPLAY (ON!OFF) SET RDISPLAY sets and resets the display of received char- acters. You may use this to suppress (OFF) received text while you wait for an appropriate response. SET RDMAX <number> A script author may set a limit to the number of redials per- formed through a DIAL statement. This feature is available only in the script that sets it (at this time). SET RECHO (ON!OFF) SET RECHO sets and resets the echo of received characters. This might be enabled (ON), for example, in a script that performed a 'HOST' mode for outside callers. SET REMAP (ON!OFF) SET REMAP enables (on) and disables (off) keyboard remapping. A remap must first be created and placed into a file COM-AND .RMP (for example using the supplied REMAP.CMD script). -> SET REMOTE (ON!OFF) SET REMOTE enables (on) and disables (off) the ability to execute script functions through received commands. REMOTE commands are received: "ESC,^,<script command> <cr>". SET RLEOK (ON!OFF) SET RLEOK sets and resets the possibility of RLE display during normal receive functions. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 94 VI. SET Commands (continued) A. Basic set (continued) SET RMODE (ASCII!BINARY) SET RMODE affects the RGET command subsequent. By default, the RMODE setting is ASCII. When set to ASCII, RGETs ignore nulls and line feeds, end on a carriage return (or length), and backspace/rubouts are implemented (and not buffered). When the mode is binary, nulls, carriage returns, line feeds, backspaces and rubouts are buffered. SET RTS (ON!OFF) SET RTS sets and resets request-to-send bit of the modem. Generally, this capability should be avoided. SET RTSD (ON!OFF) SET RTSD enables (on) and disables (off) RTS Discipline in COM-AND. When enabled, RTS is raised before every write and lowered after. When disabled, RTS is not lowered, and the script controls RTS (via SET RTS above). SET RTSF (ON!OFF) SET RTSF enables (on) and disables (off) RTS flow control. When RTS flow control is enabled the RTS line is used to signal the modem that COM-AND is able (or not able) to re- ceive characters. This method of flow control is required by some (very new) modems. Refer to Appendix J for discussion. SET SILENCE <seconds> SET SILENCE sets and resets the timeout used by ON SILENCE GOSUB. The trap defaults to 300 seconds. Note that SET SILENCE changes only the timeout, not the trap clock. SET SLOWOUT (ON!OFF) SET SLOWOUT sets and resets 'slow output' during file trans- fers. COM-AND usually performs transfers at machine speed (interrupt driven writes); Some network modems cannot take this speed. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 95 VI. SET Commands (continued) A. Basic set (continued) -> SET SOFTFLOW (ON!OFF) SET SOFTFLOW sets and resets software flow control (XON/XOFF) as used in receive and ASCII SEND. -> SET STOPBITS (1!2) SET STOP sets the communications port to 1 or 2 stop bits. -> SET SUCCESS (ON!OFF) SET SUCCESS sets and resets the SUCCESS condition tested by the IF statement. SET SUCCESS be used to modify various conditions that set/reset SUCCESS/FAILURE. -> SET SWRITE (BIOS!DIRECT!DOS) SET SWRITE sets COM-AND to use either BIOS or direct screen buffer access for menu saves/restores. Direct access is much faster (of course), however, a certain few machines are not compatible to the extent of screen memory address. SET SWRITE DOS only affects text written to the screen. When used, text received is passed to the console device. SET SWRITE BIOS affects both text written to the screen and the method used for screen saves. BIOS is used in both cases. If both SWRITE DOS and SWRITE BIOS are set, text goes through DOS, and screen save/restores go through BIOS. SET TEXT <attr> SET TEXT sets the color for text display. The change takes effect the next time a character is displayed (it does not repaint). The new color holds after the script terminates. NOTE: To change the color attribute for the entire screen: SET TEXT <attr> ; Set text attr for subsequent chars SET COLOR "_COLOR"; Repaint screen and border Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 96 VI. SET Commands (continued) A. Basic set (continued) SET TIMER [(#)] The SET TIMER instruction sets the timestamp for one of 10 timers. Timers are read using the TSINCE statement. SET TTHRU (ON!OFF) The SET TTHRU sets the script processor to allow (ON) or not allow (OFF) typethrough during the script. When set OFF, keystrokes are queued and will be read by KEYGET, ATGET, MAT- GET, GET and MGET. Note that TYPETHRU is a 'global' condition, whereas HITKEY is a 'local' condition. Typethrough is suspended after HITKEY is tested, until the key is read. Once the key is read, the HITKEY condition is disabled and typethrough is allowed (unless you've SET TTHRU OFF). Note: Use of SET TTHRU may inhibit termination with ESCape! SET TUNE <string> The SET TUNE sets the alarm tune to the BASIC encoded play statement in <string>. The ERROR condition is set if the string cannot be parsed (and the alarm is not set). Refer to Appendix C for the syntax of the play statement. SET VMOUSE # SET HMOUSE specifies the mouse vertical sensitivity. SET WAITFOR (ON!OFF) SET WAITFOR sets and resets the WAITFOR condition tested by the IF statement. SET LINKED may be used to modify the results of a WAITFOR instruction. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 97 VI. SET Commands (continued) A. Basic set (continued) SET WATCHDOG <seconds> SET WATCHDOG sets the XOFF watchdog timer timeout. When an XOFF is received a timer begins. If no XON is received with- in <timer> seconds, the XOFF condition is cancelled. WARNING: Script authors who use this command to increase the default XOFF timeout run a SERIOUS risk of locking up their machines. XOFF is a frequent noise character... Without the watchdog timer, any noise character might stop COM-AND cold. SET XSUI <number> SET XSUI sets the frequency (as an interval of blocks) with which COM-AND updates its protocol status screens during a file transfer. XSUI is mnemonic for 'xfer screen update interval'. At 9600 baud and above, the time it takes to paint the status screen becomes a significant percentage of the overall time spent. Setting the update interval to '5' will have visible impact at 2400 baud. SET ZMODEM <subcommand> The SET ZMODEM subcommands are discussed below ("VI"). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 98 VI. SET Commands (continued) B. SET ASCII subcommands -> SET ASCII BLANKEX (ON!OFF) SET ASCII BLAN sets and resets blank line expansion for the SENDFILE ASCII function (if the line is empty, one blank is sent if this flag is on). -> SET ASCII CHARPACE <number> SET ASCII CHARPACE sets an intercharacter delay (in milli- seconds for the SENDFILE ASCII function. -> SET ASCII ECHO (ON!OFF) SET ASCII ECHO enables (if set) the text echo during a SENDFILE ASCII function (only during current script). SET ASCII FLOW (ON!OFF) SET ASCII FLOW sets and resets flow control SENDFILE ASCII function. When on, flow control is respected. -> SET ASCII LINEPACE <number> SET ASCII LINE sets an delay at end-of-line (CR) in tenths of seconds for the SENDFILE ASCII function. -> SET ASCII PACECHAR <number> SET ASCII PACE sets a pace character for the SENDFILE ASCII function. The value provided is the decimal ascii value of the pace character (use 0 to turn this off). SET ASCII QUIET (ON!OFF) SET ASCII QUIET disables (if set) the alarm at the end of a SENDFILE ASCII function (only during current script). SET ASCII TABEX (ON!OFF) SET ASCII TABEX sets and resets tab expansion for the SENDFILE ASCII function. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 99 VI. SET Commands (continued) B. SET ASCII subcommands (continued) -> SET ASCII UP_LF (LF!STRIP) SET ASCII UP_LF sets and resets LF stripping during a SENDFILE ASCII function. Note that "UP_LF CR_LF" is not implemented at this time. SET ASCII UP_Z (STOP!SEND) SET ASCII UP_Z sets and resets control-z handling for the SENDFILE ASCII function. When STOP, the transfer stops at a control-z (and the control-z is not transmitted). C. SET KERMIT subcommands -> SET KERMIT 8QUOTE <number> SET KERMIT 8QUOTE sets the 8-bit quote character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the 8-bit quote character to be used. -> SET KERMIT BLOCKCHECK (1!2!3) SET KERMIT BLOCK sets the length of the blockcheck used in KERMIT transfers. This value may be inspected and changed through Alt-K. The blockcheck may be 1, 2 or 3 bytes long. -> SET KERMIT CQUOTE <number> SET KERMIT CQUOTE sets the control quote character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the control quote character to be used. -> SET KERMIT EOLCHAR <number> SET KERMIT EOLCHAR sets the end-of-line character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the end-of-line character to be used. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 100 VI. SET Commands (continued) C. SET KERMIT subcommands (continued) SET KERMIT MARK <number> SET KERMIT MARK sets the packet mark character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the packet mark character to be used. -> SET KERMIT PADCHAR <number> SET KERMIT PADCHAR sets the pad character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the pad character to be used. -> SET KERMIT PADNUM number SET KERMIT PADNUM sets the number of pad characters (if any) to be used during KERMIT transfers. This value may be inspected and changed through Alt-K. SET KERMIT REPEAT <number> SET KERMIT REPEAT sets the repeat quote character used in KERMIT transfers. This value may be inspected and changed through Alt-K. The <number> is the decimal ascii value of the repeat quote character to be used. SET KERMIT WINDOW <number> SET KERMIT WINDOW sets the maximum window size for KERMIT transfers. A window maximum of 0 stops windowed transfers. COM-AND places an upper limit on this size (currently the limit is 8). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 101 VI. SET Commands (continued) D. SET ZMODEM subcommands SET ZMODEM AUTO (ON!OFF) ZMODEM download is capable of automatically starting when the sender begins transmission. You may control whether COM-AND will automatically begin the receive. [Note that during scripted operation, auto-ZMODEM only occurs when the display is being performed.] SET ZMODEM BLOCK <number> SET ZMODEM BLOCK sets a maximum blocksize for ZMODEM sends. When a blocksize is set (rather than negotiated), the trans- fer reverts to half duplex (send, ACK, send, ACK). This is provided for special cases (badly errored lines). It is not recommended. SET ZMODEM RECOVER (ON!OFF) SET ZMODEM RECOVER enables and disables ZMODEM's recovery feature. When a receive is intended for an existing file (intended to be a the result of a previous, failed, trans- fer), the transfer will pick up at the end of file (where the last one stopped), if enabled. When disabled, transfers go to a unique file name ($ terminated as required). Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 102 VII. String Intrinsics Certain string values are treated as having an intrinsic meaning by the script processor. All intrinsic string values must have an underscore ("_") in column 0 of the string, and otherwise be alone in the string (note that only the first 4 characters of the intrinsic keyword are significant). For example: S0 = "_Date" ; is equivalent to S0 = "_DateToday" ; .. where contiguous text is ignored But S0 = "_Date today" would not be treated as containing an intrinsic value. When the script processor encounters an intrinsic function, it replaces the value with the computed value. String intrinsic functions are: _ABLA ASCII Blankexpand flag _ACCF Current accessory file _ACHA ASCII Character pace delay (ms) _ADVE ADVErt Flag on/off _AECH ASCII Echo flag _AFLO ASCII Flow control flag _ALAR ALARm Flag on/off _ALIN ASCII Line pace time (.01 ms) _ALLO 0,1,2... number of dynamic variables allocated _APAC ASCII Pace character (Decimal ASCII value) _AQUI ASCII Quiet flag _ATAB ASCII tab expand flag _ATIM Alarm time (secs) _AUPZ ASCII Send ctl-z flag (STRIP!SEND) _BAR (numeric) Status line color attribute _BELL Bell tone (hz) _BKSC Backscreen buffer size (pages) _BREA Break duration (ms) _BSIN Backspace IN (NONDESTRUC!DESTRUC) _BSOU Backspace out (BACKSP!DELETE) _BSUP BSUPpress Flag on/off _CALL Last dialed dialing directory entry _CDIS Control-char display flag on/off _CDRE CDREspect Flag on/off _CHAT CHAT Flag on/off _CHLI Chat lines _CLFI Call Log file name Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 103 VII. String Intrinsics (continued) _CLOC CLOCk Flag on/off _CLOG CLOGging Flag on/off _COLO Color flag on/off _CONN Connection (formatted: Y/N) _CRLF CR -> CRLF flag (ON, OFF values, ON = CR->CRLF) _DATE Current date (formatted: mm/dd/yyyy) _DBLC Double click interval in MS _DEFA (numeric) Menu window color attribute _DIRF Current dialing file _DLDI Read current download drive:subdirectory _DOW Day of week (0 -> Sunday, 1 -> Monday, etc) _DPRE Dialing prefix (from Alt-S) _DROP Drop DTR flag _DSUF Dialing suffix (from Alt-S) _DUPL Duplex setting (HALF!Full) _EFFI Last transfer efficiency _ELAP Elapsed time since call (formatted hh:mm:ss:tt) _EMUL EMULATION (TTY!ANSI!VIDTEX!...) _ERRO Last transfer error text (formatted: nn: text) _EXIT Return current exit script name _EXQU EXit QUery Flag on/off _FLOW (soft) FLOW Flag on/off _HARD Hardware flow control flag _HMOU Mouse horiz (mickeys) _IFIL FOPENI (script input) file name _INAF Init modem after hangup on/off _K8QU KERMIT 8 bit quote _KBDB KBDBuf Flag on/off _KCHK KERMIT Block check _KCQU KERMIT control quote char _KEOL KERMIT EOL char _KMAR KERMIT Mark char _KNUM KERMIT number pads _KPAD KERMIT pad char _KREP KERMIT Repeat char _KWIN KERMIT max window _LEGE Returns last LEGEND string displayed (or null) _LOGG LOGging Flag on/off _LOGH LOG Held Flag on/off _LOGM LOGMarked Flag on/off _MACF Current macro file _MASK (7 bit) MASK Flag on/off _MCON Modem connect string (from Alt-S) _MDCH Modem delay char _MDEL Modem character delay (ms) Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 104 VII. String Intrinsics (continued) _MENU Menu mode Flag on/off _MESC Modem escape string (from Alt-S) _METH Last transfer method _MHAN Modem hangup string (from Alt-S) _MINI Modem initialization string (from Alt-S) _MOUS Return mouse presence: YES/NO _MUSI MUSIc Flag on/off _NULL Null value (empty string) _OFIL FOPENO (script output) file name _ONES Current ON ESCAPE GOSUB label (8 characters) _OVER Return OVERLAY file name last loaded (or null) _PARM Current comm parms (formatted as COMPARM statement) _PCJR PCJR Flag on/off _PRIN PRINter Flag on/off _QUIE QUIEt Flag on/off _RDEL Reconnect delay (secs) _RDIS RDISplay Flag on/off _RDMA ReDial MAximum value (0 -> no limit set) _RDPN ReDial Pass Number on which CONNECT last occurred _RECH RECHo Flag on/off _REMA Remapping on/off _REMO REMOte Flag on/off _RLEO RLEOk Flag on/off _RTSD RTSDiscipline Flag on/off _RTSF RTSFlow control on/off (a type of hdwe flow control) _RUNT Return Runtime invocation: YES/NO (see below) _SCRI Current script file name _SILE Duration (in MS) of ON SILENCE timeout _SIZE Last transfer size _SLOW SLOW Flag on/off _SSIZ Current screen size (# lines) _SUBD Read current drive:subdirectory _SWRI Screen write (DOS!BIOS!DIRECT) _TEXT (numeric) Text window color attribute _TIME Current time (formatted: hh:mm:ss:tt) _TRAN In/Out Translate on/off _TRFI Last transfered file (except multiple transfers) _TRTI Last transfer time _TTHR TTHRu Flag on/off _UART Return UART type (-1,0,...3: see below) _VMOU Mouse vert (mickeys) _XSUI Transfer screen update interval _ZAUT ZMODEM auto download flag _ZBLO ZMODEM maximum blocksize _ZREC ZMODEM download recovery flag Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 105 VII. String Intrinsics (continued) Intrinsic returned values are left justified in the string (with the exception of "_PARM", which does not justify " 300" in the string). The returned value may or may not be blank padded. [Blank padding is of concern in some cases. The construction 'Sx = Sx&""' may be used to remove trailing spaces.] Note that when a batch file transfer is performed (e.g. KERMIT), only the last file name transfered is reported. In the case of ZMODEM and YMODEM-Batch the file name is always null, by definition of the protocols. The file transfer intrinsics only refer to binary protocols. They do not report ASCII transfers. The "_UART" intrinsic returns the values -1,0,1...3 according to the UART type found when the current port was opened. These values mean: -1 -> No UART was detected 0 -> 8250 type UART detected (NO FIFO bufferring) 1/2 -> 16450/16500 UART detected (NO FIFO bufferring) 3 -> 16550A type UART detected (FIFO bufferring) The "_RUNT" intrinsic may be used to distinguish automatic scripts (COM-AND.CMD and INSTALL.CMD) from all other scripts. These scripts are automatically invoked at run-time (INSTALL being invoked only in certain cases). "_RUNT" returns YES during automatic run-time scripts. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 106 VIII. Script Errors Errors are reported in the form: <line #>: <error text> Error texts are: Invalid token Unexpected end of file Unexpected token Missing token Stack overflow Stack underflow Unexpected characters at end of line Unexpected CASE Unexpected DEFAULT Unexpected ENDCASE Unexpected ENDSWITCH Unexpected ELSE Unexpected ENDIF Unexpected RETURN Unexpected ENDFOR Unexpected UNTIL Unexpected ENDWHILE Unexpected FRETURN Note: COM-AND does not terminate in all cases where an error is encountered. Stack over/underflow errors always terminate a script, as do the unexpected CASE/DEFAULT/ENDCASE/ENDSWITCH/ ELSE/ENDIF/RETURN errors. Unexpected end-of-file (when a GOTO branches to a label that does not exist) terminates the script. Other errors do not terminate the script. Note: PROCOMM does not accept a command on a labelled line. However, PROCOMM does not issue an error message at that point either. COM-AND will report 'unexpected characters at end of line' when this is encountered, and ignore the command. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 107 IX. ASPECT and PROCOMM 2.4.2 scripts COM-AND will execute most scripts written for PROCOMM 2.4.2 and for the ASPECT script language (tm DataStorm). However, the ASPECT language is only a subset of the COM-AND script language. Although COM-AND will execute most PROCOMM scripts, PROCOMM will not execute most COM-AND scripts. To retain ability to execute a script you write under PROCOMM: o ONLY use statements marked '->' in the discussion above. These statements are compatible with the ASPECT language. o ONLY use constructions highlighted '->' in the discussion above. For example: COM-AND will accept (and PROCOMM won't): STRCAT S0 S1(5:10) ; Extract substring and concatenate o REFER to the PROCOMM document (or ASPECT manual for full dis- cussion of ANY statement you wish to employ. o Avoid numeric variables N10-N99 o Avoid string variables S10-S29 o Avoid ALL string variables V0-Vn o Avoid ALL usage of FLAG variables o Use full keywords; do not abbreviate to 4 characters. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 108 IX. ASPECT and PROCOMM 2.4.2. scripts Unimplemented ASPECT commands ----------------------------- Every attempt has been made to provide a script language that is compatible with PROCOMM. However, certain commands do not apply to COM-AND. Others have been changed for more of less obvious reasons. Changes and optional usages have been highlighted above. The following ASPECT commands have not been implemented: * HELP * HOST * KERMSERV FINISH * KERMSERV GETFILE * KERMSERV LOGOUT * KERMSERV SENDFILE * SET ASCII DN_CR (CR!CR_LF!STRIP) * SET ASCII DN_LF (LF!CR_LF!STRIP) * SET ASCII UP_CR (CR!CR_LF!STRIP) * SET CR_OUT (CR!CR_LF) * SET ENQ ON ; SET ENQ OFF!CISB implemented * SET HOSTPSWD <string> * SET KERMIT PACKSIZE <number> * SET KERMIT HANDSHAKE <number> * SET KERMIT FILETYPE (TEXT!BINARY) * SET SCROLL (ON!OFF) * SET SHELLPSWD <string> * SET SOUND (ON!OFF) * SET TXPACE <number> ; Partially implemented as SET ASCII CHARPACE * SET WRAP (ON!OFF) * SNAPSHOT Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 109 X. Program Requirements This program will only function on an IBM PC or DOS compatible machine. COM-AND does direct to screen buffer fetches and stores (unless BIOS screen updates are directed using the /C switch or the Alt-O options menu). COM-AND is TopView aware even without the /C switch or Alt-O option. COM-AND supports MDA, CGA, EGA and Hercules. COM-AND uses a Micro- soft Mouse if one is available... COM-AND disk I/O is done through the 'Handle' oriented I/O routines added to DOS 2.0. Therefore DOS 2.0 is a minimum requirement. COM-AND (Version 2.7) requires 252K for itself. You need 384K minimally to use COM-AND and the DOS Gateway, and more to take advantage of accessories. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 110 XI. Program and Author Information This program was written using Microsoft Macro-Assembler. The author likes assembler. Assembly language is an entirely appropriate vehicle for some of the program, and a not-inappro- priate vehicle for the rest of it. Everything, in moderation... COM-AND has been written by, and is supported by R. Scott McGinnis of Chicago (CABER Software), Illinois. My PLINK and GEnie IDs are: TARTAN. My CIS ID is 73147,2665. Comment and suggestions (and criticism in moderation) are welcomed: CABER Software R. (Scott) McGinnis P.O. Box 3607 Mdse Mart Chicago, IL 60654-0607 I must thank Mike Todd and John Poindexter of the Source for their strenuous testing and excellent suggestions. Mike and John have pushed me hard, and I thank them. This script language is in large part shaped by these gentlemen. I also thank my wife, Elizabeth, who supported me whole-heartedly in this effort. She is my lady and my love. This program (Version 2.7) may be distributed freely along with its accessories with the caveat that the Author information displayed at program termination is not removed. If the program is USED after a reasonable period of evaluation, a registration of $35.00 is required. PROCOMM, PCPLus, and ASPECT are trademarks of the DataStorm cor- poration. DSZ is a trademark of OMEN Technology. Windows is a trademark of the MicroSoft Corporation. DesqView is a trademark of the QuarterDeck Corporation. Smartmodem is a trademark of the Hayes Corporation. Version 2.7: 901015 COM-AND: IBM PC Communication Script Language Page 111 A. Example scripts A script to dial a modem direct, send two carriage returns, and wait for a logon prompt looks like: ------------------------------------------------------------------ DEFTIME "60" ; Wait 60 seconds for an incoming string IF NOT LINKED ; If script not invoked from Alt-D MESSAGE "^GDialing direct" DIAL "1" ; Call dial dir entry number 1 (PLINK) IF FAILED ; IF esc out EXIT ; terminate script ENDIF ; End if failed ENDIF ; End if not linked PAUSE "5" ; Wait for the modem to settle down TRANSMIT "!" ; Transmit Carriage return <CR> PAUSE "1" ; Wait 1 sec TRANSMIT "!" ; Transmit Carriage return <CR> WAITFOR "USER ID:" ; Wait for the 'USER ID' prompt SET BSUPPRESS OFF ; Turn off blank line suppression SET MASK ON ; Turn on high bit mask SET CDISPLAY ON ; Display control characters ALARM ; Sound alarm: we're done ------------------------------------------------------------------- Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 112 A. Example scripts (continued) A script to dial GEnie, and logon makes special provisions to turn echo off (mask it, anyway) during logon: ------------------------------------------------------------------ DEFTIME "60" ; Wait 60 seconds for an incoming string IF NOT LINKED ; If not from Alt-d MESSAGE "^GDialing GEnie direct" DIAL "4" ; Call dial dir entry number 4 (GEnie) IF FAILED ; IF esc out EXIT ; terminate script ENDIF ; Endif failed ENDIF ; End test if linked PAUSE "3" ; Wait for the modem to settle down TRANSMIT "hhh" ; Transmit WAITFOR "U#=" ; Wait for the 'USER ID' prompt SET BSUPPRESS ON ; Turn on blank line suppression SET MASK ON ; Turn on high bit mask SET CDISPLAY OFF ; Control character display SET DUPLEX FULL ; Turn off local echo for ID/psw ALARM ; Sound alarm MESSAGE "^MEnter ID,password for GEnie:" MGET S0 ; Get ID/psw TRANSMIT S0 ; Transmit ID/psw TRANSMIT "^M" ; .. and a final c/r SET DUPLEX HALF ; Turn echo back on ------------------------------------------------------------------ Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 113 A. Example scripts (continued) A script to dial Telenet (entry number 10 in the dialing directory assumed, and make connection according to the parameters set looks like: ------------------------------------------------------------------ LEGEND " Dialing Telenet... " DEFTIME "60" ; Wait 60 seconds for an incoming string IF NOT LINKED ; If script not invoked from Alt-D DIAL "10" ; Call dial dir entry number 10 (Telenet) IF FAILED ; IF esc out EXIT ; terminate script ENDIF ; End if failed ENDIF ; End if not linked COMPARMS S1 ; Get current settings IF STRCMP "N" S1(5:5) ; If no parity IF STRCMP "2400" S1(0:3) ; If 2400 baud connect Send @D<cr> PAUSE 1 ; Wait for the modem to settle TRANS "@" ; Send @D<cr> slowly PAUSE 1 ; Wait a moment TRANS "D" ; Set to 8N1 PAUSE 1 ; Wait a moment ELSE ; ELSE 300/1200 (send <cr>D<cr>) PAUSE "1" ; Wait for the modem to settle TRANSMIT "!D" ; Transmit Carriage return <CR> D ENDIF ELSE ; ELSE even or odd parity PAUSE "1" ; Wait for the modem to settle TRANSMIT "!" ; Transmit Carriage return <CR> ENDIF PAUSE "1" ; Wait 1 sec TRANSMIT "!" ; Transmit Carriage return <CR> WAITFOR "TERMINAL=" ; Wait for the prompt TRANSMIT "D1!" ; Set terminal type WAITFOR "@" ; Wait for next prompt SET BSUPPRESS OFF ; Turn off blank line suppression SET MASK ON ; Turn on high bit mask SET CDISPLAY ON ; Display control characters ALARM ; Sound alarm: we're done ------------------------------------------------------------------ Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 114 B. HOST and BBS scripts Supplied with this release of COM-AND are two large scripts. HOST.CMD supports a limited Host mode for callers to your PC; BBS.CMD supports a more extensive BBS function (with multiple users, mail, upload/download files, bulletins and so on). The advantage of a scripted HOST or BBS mode is flexibility. You may use the script as supplied, or tailor it to your needs. As the supplied scripts use a public domain graphic path display utility (TREED), you will want to remove the function (at least the prompt for it) if you don't have the program. You may wish to add other functions. Documentation has been provided with each of the scripts. For those interested in having a simple HOST mode, or a simple BBS, refer to the BBS&HOST archive included with this distribution. The supplied HOST and BBS scripts work best if your modem is set to report the real state of Carrier Detect (CD). However, it has been used quite successfully with modems that report Carrier Detect always true (when disconnect occurs, Hayes compatible modems report the fact with 'NO CONNECT'). These scripts are offered mostly as examples of the script language. Should you feel inclined to rewrite one or the other of these scripts, contact the author. I would be happy to replace what I've included with a superior effort! Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 115 C. External protocol drivers COM-AND supports external protocol drivers through its F1 (access- ories) menu. You may edit the entries in the F1 menu to load and execute just about any program you might wish (and have memory for). If you limit the F1 entries to simple script invocations, you may also use the script name through F2. For example, you might wish to use a different implementation of ZMODEM than COM-AND's. [COM-AND implements a complete ZMODEM. How- ever, some of the management and transfer options are not available through COM-AND.] You might do this with Chuck Forsberg's DSZ.COM program, if you have registered it. DSZ is a module that may be run from within other comm programs to perform ZMODEM transfers (and X/Ymodem transfers too). DSZ is revised quite often (to expand its function), and is available on most systems. For downloading purposes, no script is needed to invoke DSZ. How- ever, as mentioned above, the F1 entry will be coded to use a script to allow the same script to be manual invoked through F2. The file name used for the downloaded file will be determined by the sender. Revise an F1 entry (with the 'r' subcommand) as follows: Name: Download using YMODEM Subdirectory: (whatever subdirectory your DSZ occupies) Program: (leave this field blank) Script: DSZDOWN.CMD The script DSZDOWN.CMD could be written: ------------------------------------------------------------------ COMPARMS S1 ; read current settings S2 = "DSZ.COM port " * S1(14:14) * " rb " ; Ask for YMODEM rcv RUN S2 ; Load and run DSZ ------------------------------------------------------------------ Note: change " rb " to " rz " for ZMODEM ------------------------------------------------------------------ Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 116 C. External protocol drivers (continued) DSZ requires a file name for uploading. You may accomplish this by editing the F1 menu as follows, and creating the following script to request a file name and load DSZ. Name: Upload using YMODEM Subdirectory: (whatever subdirectory DSZ/DSZUP occupies) Program: (leave this field blank) Script: DSZUP.CMD The script DSZUP.CMD could be written: ------------------------------------------------------------------ MESSAGE "^MEnter the upload file name: " GET S0 ; Read keyboard COMPARMS S1 ; read current settings S2 = "DSZ.COM port " * S1(14:14) * " sb " * S0 ; ask for YMODEM sb" RUN S2 ; Load and run DSZ ------------------------------------------------------------------ Note: change " sb " to " sz " for ZMODEM ------------------------------------------------------------------ DSZ defaults to COM1 and your current baud rate. The above scripts adjust for the comm port you're using. The above scripts (or better) are included in the SCRIPTS.ARC file released with COM-AND. NOTE: DSZ is user supported. If you use it, please register it! DSZ may be found on most bulletin boards, and on every major system. Registration information is provided with every release of DSZ. NOTE: More functional scripts for invocation of DSZ are included in the scripts ARC file released with COM-AND. A pop-up window is used to query the file name, and so on. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 117 D. Encoded music Beginning with version 2.3, COM-AND uses encoded music strings for several different purposes: . If the file COM-AND.TUN exists on the default drive:subdirectory (or on the COM-AND= drive:subdirectory), and it contains a valid encoded music string (not to exceed 40 notes), COM-AND will use the encoded string for its alarm. . The alarm tune may be changed with a "SET TUNE" command through a script file. The new alarm tune holds until it is changed, or until COM-AND is terminated. . A script may PLAY an encoded music string during its execution (up to 80 notes). . An escape sequence to play music has been implemented (for some RBBS boards). The escape sequence is "ESC [M <music string> ^N" allowing up to 255 characters for the <music string>. Music strings are encoded using the BASICA 2.0 PLAY statement syntax. Commands are single characters, followed by one or more parameters. Blanks and commas are allowed for readability. Case is not signifi- cant. Commands are: . A through G: Play a note in the current octave A note command plays a note in the current octave. It may be optionally followed by: (1) # (sharp), + (sharp), and - (flat), (2) a duration value (1 through 64, see "L" below), and (3) one or more periods (dotting) extending the duration by 3/2. If no duration number is specified the duration is the current default (set by "L", beginning at 4 with each string). Example: A-16 A-flat in the current octave (sixteenth note) Blanks and commas ARE NOT allowed within the note declaration; e.g. no blank should occur between the command and a flat/sharp. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 118 D. Encoded music (continued) . O # Set the current octave There are 7 octaves, numbered 0 through 6. Middle-C begins octave number 3. Each string defaults at the start to octave number 4. . > Raise the octave by 1 The current octave is raised with this command. . < Lower the octave by 1 The current octave is lowered with this command. . N # Play note number 0-84 Each octave contains 12 notes (C,C#/D-,D,D#/E-, etc). Notes are numbered from the 0th octave beginning with 1. 0 is a rest. Note numbers may be followed by duration (blank separated from the note number) and dotting as in the note command. Example: N36 4. Middle-C, 3/8ths (dotted quarter) . L # Set default duration for following notes The duration of a note is specified as a number, 1 through 64. L1 is a whole note, L2 is a half note, L3 is a triplet, L4 is a quarter note, and so on. The actual duration (in time) for notes is set through the T (Tempo) command, below. . P Pause (rest) Rests may be encoded, using this command with duration and dotting as with the note command. Example: P1. Pause for a whole and a half . T # Tempo (number of quarter notes per minute) Tempo is specified as a count of quarter notes per minute. The tempo is allowed to range between 32 and 255, defaulting to 120. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 119 D. Encoded music (continued) . MN Normal Each note plays 7/8ths of the time specified (1/8th silence). . MS Staccato Each note plays 3/4s of the time specified (1/4 period silence). . ML Legato Each note plays the full period specified. Each encoded music string is an entity itself. Defaults are reset at the beginning of each string. Defaults are: T120,O4,L4,MN For example, the DRAGNET "dum-dee-dum dum" might be played: PLAY "ms t250 o2 c2d8e-cp4g-1 p2 >c2d8e-cp4g-1 p2" Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 120 E. File transfer error numbers COM-AND reports file transfer errors with a number and an explanation on the screen. When an error is logged to the call-log, however, COM-AND only logs a number. Error numbers are: DOS errors: 1 Invalid function number (from INT 21H) 2 File not found 3 Path not found 4 Too many open files (no handles left) 5 Access denied 6 Invalid Handle 7 Memory control blocks destroyed 8 Insufficient memory 9 Invalid Memory block address 10 Invalid environment 11 Invalid format 12 Invalid access code 13 Invalid data 14 Short write. Disc Full? Error # generated here 15 Invalid drive was specified 16 Attempted to remove current directory 17 Not same device 18 No more files Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 121 E. File transfer error numbers (continued) Program errors (internally generated): 1 Other side cancelled ; All 2 Handshake failed ; .. 3 Block sequence error ; .. 4 Complement error ; .. 5 Checksum mismatch ; .. 6 CRC mismatch ; .. 7 Short block received ; .. 8 We cancelled ; .. 9 NAK rcvd/xmitted - retrying ; .. 10 Timeout ; .. 11 Cancelled by operator ; .. 12 Timeout waiting for rcvr ACK ; .. 13 ENQ received during block ; CISB 14 Unrecognized command received ; .. 15 ETX received ; .. 16 Buffer overflow ; .. 17 Wait ACK received from CIS ; .. 18 Send initiate received ; Kermit 19 File Header received ; .. 20 Send-initiate sent ; .. 21 End-of-transfer sent ; .. 22 Other side not using batch ; Batch-Ymodem 23 File name not received ; .. 24 Negotiation packet received ; CIS Quick-B 25 Application inquiry packet received ; CIS Quick-B 26 Insufficent space for rcv ; KERMIT/Batch YMODEM 27 Carrier has been dropped ; All 28 ZMODEM frame end ; ZMODEM (internal) 29 ZMODEM encryption requested ; ZMODEM 30 ZMODEM file skipped ; ZMODEM 31 ZMODEM waiting recovery ; ZMODEM (internal) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 122 F. EBL (Extended Batch Language) Extended Batch Language (EBL) is a command programming language that may be used as a direct replacement of DOS batch files. It may also be used in conjunction with DOS batch files. A superb example of EBL's power may be seen in the system SIGCOM, which is a communications system for use in the IBMSIG on UNISON (originally created for The SOURCE). SIGCOM uses EBL to integrate COM-AND with the editor EDWIN and Vern Buerg's LIST. One of the unique features of EBL is its global variables ( %A..%O ). String or numerical values may be assigned to the global variables through EBL batch files. Once a value is assigned to one of these 15 variables it is accessible to other EBL files until it is re- assigned. This is a powerful feature which allows the passing of parameters from one EBL file to another. COM-AND makes these global variables available for use in script files through its EBL script command. The global variables are much more useful than variables in the DOS environment since the global variables are not dependent on whether they are assigned in a child or parent process. Global variables may be set by an EBL file run through COM-AND and then be available to other EBL files run through other COM-AND script files, or run from DOS after exiting COM-AND. This is not true of normal DOS environment variables. In a multi-tasking environment such as DESQview each window has its own DOS environment and there is no convenient way to pass DOS environment variables from one window to another. With the COM-AND EBL command the capability exists to pass data from one window to COM-AND in another window through the EBL global variables. Extended Batch Language may be obtained from SEAWARE Corporation, P.O. Box 1656, Delray Beach, FL 33444, 800-634-8188 or 407-392-2046. Registration fee is $49. Extended Batch Language is copyrighted by Seaware Corp. 1982,83,84,85,86,87. The latest version of SIGCOM, the communication system for using the features of UNISON and the IBM Special Interest Group (IBMSIG), is always available from Mike Todd on UNISON via the ID MIKETODD or the IBMSIG EXCHANGE topics in PARTI for details on downloading or having diskettes mailed to your door. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 123 G. Manual settings and scripts 1. Alt-S (Setup window) 1) Modem init string SET MINIt <str> _MINI 2) Modem dial prefix SET DPREfix <str> _DPRE 3) Modem dial suffix SET DSUFfix <str> _DSUF 4) Hang-up string SET MHANg <str> _MHAN 5) Escape string SET MESCape <str> _MESC 6) Connect string SET MCONnect <str> _MESC 7) Call log file CLOG OPEN <str> _CLFI 8) Dialing directory DLOAD <str> _DIRF 9) Macro directory MLOAD <str> _MACF 10) RLE temp file ----- ----- 11) Accessory direc ALOAD <str> _ACCF 12) Backscreen Buffer SET BKSC # _BKSC 13) Break delay SET BREAK # _BREA 14) Alarm duration SET ATIME # _ATIM 15) Modem character delay SET MDELay # _MDEL 16) Reconnect delay SET RDELay # _RDEL 17) Chat window size SET CHLInes # _CHLI 18) Mouse vertical SET VMOUse # _VMOU 19) Mouse horizontal SET HMOUse # _HMOU 20) Mouse dbl click interval SET DBLCLICK # _DBLC 21) Bell tone SET BELL # _BELL 22) Modem delay character SET MDCHAR # _MDCH 23) Xfer screen upd SET XSUI # _XSUI 24) Save these values UPDATE (*) RESET (*) Note: UPDATE and RESET do not apply to these settings alone. Both commands (UPDATE and RESET) apply to ALL Alt-S, Alt-O, Alt-P, Alt-K, Alt-J settings. RESET further closes and re- opens the comm port. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 124 G. Manual settings and scripts (continued) 2. Alt-O (Options window) 1) Echo received characters SET DUPLEX HALF!FULL _DUPL 2) Mask received characters SET MASK ON!OFF _MASK 3) Keyboard display SET KBDBuf ON!OFF _KBDB 4) Chat mode SET CHAT ON!OFF _CHAT 5) Suppress blank lines SET BSUPpress ON!OFF _BSUP 6) Alarm noise SET ALARM ON!OFF _ALAR 7) Exit query (Alt-X) SET EXQUery ON!OFF _EXQU 8) Mark transcript LOG MARKED ON!OFF _LOGM 9) Initial advertisement SET ADVERT ON!OFF _ADVE 10) Use BIOS for screen saves SET SWRITE BIOS!DIRECT _SWRI 11) Use DOS for screen writes SET SWRITE DOS!BIOS!DIRECT _SWRI 12) Display control characters SET CDISPlay ON!OFF _CDIS 13) Perform XON/XOFF Flow ctl SET FLOW ON!OFF _FLOW 14) Perform hardware Flow ctl SET HARD ON!OFF _HARD 15) Use RTS(hardware) Flow ctl SET RTSF ON!OFF _RTSF 16) Drop DTR to hangup SET DROP ON!OFF _DROP 17) Init modem after hangup SET INAF ON!OFF _INAF 18) Translate (in and out) SET TRANslate ON!OFF _TRAN 19) Keyboard remapping SET REMAP ON!OFF _REMA 20) Nondestructive bksp SET BACK IN (NOND!DEST) _BSIN 21) Send DELETE as bksp SET BACK OUT (BACK!DELE) _BSOU 22) CR -> CRLF in display SET CR CR!CRLF _CRLF 23) Call logging on SET CLOG ON!OFF _CLOG 24) On screen clock SET CLOCK ON!OFF _CLOC 25) Suppress bells SET QUIET ON!OFF _QUIE 26) Menu mode SET MENUMODE ON!OFF _MENU 27) Respect modem CD SET CDRESpect ON!OFF _CDRE 28) PCJr (disc suspends comm) SET PCJR ON!OFF _PCJR 29) Capture/display RLE files SET RLEOk ON!OFF _RLEO 30) Allow MUSIC strings SET MUSIC ON!OFF _MUSI 31) Allow REMOTE commands SET REMOTE ON!OFF _REMO 32) Set slow xfer output SET SLOW ON!OFF _SLOW 33) Auto ZMODEM download SET ZMODEM AUTO ON!OFF _ZAUT 34) ZMODEM download recovery SET ZMODEM RECOVER ON!OFF _ZREC 33) Save these values UPDATE (*) RESET (*) Note: UPDATE and RESET do not apply to these settings alone. Both commands (UPDATE and RESET) apply to ALL Alt-S, Alt-O, Alt-P, Alt-K, Alt-J settings. RESET further closes and re- opens the comm port. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 125 G. Manual settings and scripts (continued) 3. Alt-P (Parameters window) 1) 300,E,7,1 SET BAUDRATE 300, +below _PARM 2) 1200,E,7,1 SET BAUDRATE 1200,+below " 3) 2400,E,7,1 SET BAUDRATE 2400,+below " 4) 4800,E,7,1 SET BAUDRATE 4800,+below " 5) 9600,E,7,1 SET BAUDRATE 9600,+below " 6) 19200,E,7,1 SET BAUDRATE 19K, +below " .. .. .. " 10) 300,N,8,1 SET BAUDRATE 300, +below " 11) 1200,N,8,1 SET BAUDRATE 1200,+below " 12) 2400,N,8,1 SET BAUDRATE 2400,+below " 13) 4800,N,8,1 SET BAUDRATE 4800,+below " 14) 9600,N,8,1 SET BAUDRATE 9600,+below " 15) 19200,N,8,1 SET BAUDRATE 19K, +below " .. .. .. " 19) EVEN SET PARITY EVEN " 20) ODD SET PARITY ODD " 21) NONE SET PARITY NONE " 22) 7 bits SET DATABITS 7 " 23) 8 bits SET DATABITS 8 " 24) 1 bit SET STOPBITS 1 " 25) 2 bits SET STOPBITS 2 " 26) COM1 SET PORT COM1 " 27) COM2 SET PORT COM2 " 28) COM3 SET PORT COM3 " 29) COM4 SET PORT COM4 " 30) Set base/IRQ SET COMBASE; COMBASE <port> Nx SET COMVECT; COMVEC <port> Nx 31) Save UPDATE (*, see Alt-S) RESET 4. Alt-K (KERMIT defaults window) 1) Mark character SET KERMIT MARK # _KMAR 2) Number of pads SET KERMIT PADNUM # _KNUM 3) Pad character SET KERMIT PADCHAR # _KPAD 4) Packet terminator SET KERMIT EOLCHAR # _KEOL 5) Control quote SET KERMIT CQUOTE # _KCQU 6) Binary quote SET KERMIT 8QUOTE # _K8QU 7) Check field len SET KERMIT BLOCKCHECK 1!2!3 _KCHK 8) Compression flag SET KERMIT REPEAT # _KREP 9) Max window size SET KERMIT WINDOW # _KWIN 10) Reset to default values ----- 11) Save current values UPDATE (*, see Alt-S) RESET Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 126 G. Manual settings and scripts (continued) 5. Alt-J (Colors window) 1) Color SET COLOR ON!OFF _COLO 2) Text foreground COLOR <attr>, SET TEXT _TEXT 3) Text background " " " 4) Menu foreground SET DEFAULT <attr> _DEFA 5) Menu background " " 6) Screen bar foreground SET BAR <attr> _BAR 7) Screen bar background " " 8) Save these values UPDATE (*, see Alt-S) RESET 6. Help (General help list) F1 -- Accessories ACCESSORY # F10 - This screen ----- Alt-F10 - DOS Gateway SHELL Ctl-End - Break BREAK [#] F2 -- Perform script EXECUTE <string> F3 -- Current d:subdir CHDIR <string> F4 -- DLoad d:subdir SET DLDIR <string> F5 -- ASCII Upload SENDFILE ASCII <name> F6 -- ASCII Download GETFILE ASCII <name> F7 -- Toggle disc log LOG OPEN <str>,LOG CLOSE F8 -- Toggle KBD disp SET KBDBuf ON!OFF F9 -- Toggle log hold LOG SUSPEND, LOG RESUME PgUp Upload a file SENDFILE <method> ... PgDn Download a file GETFILE <method> ... Alt-0/9 Execute a macro MACRO # Ctrl-PrtSc Toggles printer SET PRINTER ON!OFF Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 127 G. Manual settings and scripts (continued) 6. Help (continued) Alt-A - Toggle Chat mode SET CHAT ON!OFF Alt-B - Redisplay ----- Alt-C - Clear screen CLEAR <attr> Alt-D - Dial DIAL # Alt-E - Toggle echo SET DUPLEX FULL!HALF Alt-F - File directory DIR Alt-G - Toggle blank-lines SET BSUP ON!OFF Alt-H - Hang up HANGUP Alt-I - Program info VERSION Sx Alt-J - Set screen colors above Alt-K - Set KERMIT parms above Alt-L - Toggle 25/43 lines SET 25, SET 43 Alt-M - Define a macro SET MACRO # <string> Alt-N - Encrypt/Decrypt ENCRYPT ..., DECRYPT ... Alt-O - Set options above Alt-P - Set comm params above Alt-R - Redial last number DIAL Alt-S - Initial values above Alt-T - Time(s) and alarm SET ALARM Alt-U - Annotate call log CLOG <string> Alt-V - Emulation EMULATE <method> Alt-W - Playback TYPE <string> Alt-X - Terminate program BYE Alt-Z - Toggle 7bit mask SET MASK ON!OFF Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 128 H. STACK and Macro keycodes COM-AND application keystrokes may be created in a script itself. The script must (1) turn off the keyboard, (2) stack the keystrokes and (3) terminate the script. For example, making a script: SET TTHRU OFF ; Turn off keyboard STACK "^@<SOURCE!" ; Stack command to invoke F2 EXIT ; Terminate script to execute actually invokes the F2 (execute script) window, and passes the name "SOURCE" with a terminating carriage return to the F2 window. The ^@ indicates that the following character is to be interpreted as an 'extended keystroke', i.e. not-ASCII. The extended character set is: Macro seq Key Macro seq Key Macro seq Key --------- --- --------- ----- --------- ----- ^@; F1 ^@^^ Alt-A ^@1 Alt-N ^@< F2 ^@1 Alt-B ^@^X Alt-O ^@= F3 ^@. Alt-C ^@^Y Alt-P ^@> F4 ^@ (space) Alt-D ^@^P Alt-Q ^@? F5 ^@^R Alt-E ^@^S Alt-R ^@@ F6 ^@! Alt-F ^@^_ Alt-S ^@A F7 ^@" Alt-G ^@^T Alt-T ^@B F8 ^@# Alt-H ^@^V Alt-U ^@C F9 ^@^W Alt-I ^@/ Alt-V ^@D F10 ^@$ Alt-J ^@^Q Alt-W ^@I PgUp ^@% Alt-K ^@- Alt-X ^@Q PgDn ^@& Alt-L ^@^U Alt-Y ^@u Ctl-End ^@2 Alt-M ^@, Alt-Z Note, too, that Alt-A (requiring "^^") is unprogrammable. It may be entered as decimal 30 (use Alt and numeric pad keys). In the above example, the F2 key was represented by "^@<". When the F2 key is pressed a window is opened and a search for all files *.CMD and *.ENF takes place. In simpler terms, pressing the F2 key takes TIME. COM-AND defines the ASCII value 255 as a short cut to execute a script. The macro: " SOURCE!" has the same effect, and doesn't open the script window. If the first character following the 255 is ".", the text will be executed as a single script command. Other- wise, the text is interpreted as a script file name to be executed. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 129 I. Dynamic String Variables With version 2.6, script authors may now ALLOCATE string variables in addition to the 30 static string variables always available. The variables are used as V0,V1,... and may be used in any statement now now supporting static string variables (S0,S1...). There are a few differences, however. o Allocated variables must be ALLOCATEd before they are used, once in a COM-AND session. They do NOT necessarily need to be ALLOCATEd in the script that invokes them, however. o Allocated variables are NOT deallocated when a script ends. o Allocated variables are NOT cleared when a script terminates. One script may set values and a second may read them. o Allocated variables ARE deallocated when COM-AND terminates. Dynamic variables are allocated from free memory, over and above the memory used by COM-AND normally. Therefore, not all PC installations will allow dynamic allocation. The ALLOCATE and LOAD ALLOCAT state- ments return SUCCESS/FAIL according to the result of the operation. A script author should only ALLOCATE as many variables (limited to 100 max) as absolutely needed. Some large script systems will ALLOCATE variables and expect the area to be available during an entire COM-AND session. Other scripts will have need for extended variables, but only during the single script's execution. In a one-time case, the following is suggested: On initialization: DELETE "Script.dat" ; Delete this script's save file STORE ALLOC "Script.dat" ; Save current allocation, if any ALLOCATE <number> ; Deallocate and allocate anew IF FAILED ; If allocation failed MESS "Cannot allocate memory for variables" ... ENDIF On termination: DEALLOCATE ; Clear our allocation IF ISFILE "Script.dat" ; If something previously allocated LOAD ALLOCATED "Lister.dat" DELETE "Lister.dat" ; Delete same file ENDIF Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 130 I. Dynamic String Variables (continued) For the author preparing a suite of scripts expecting dynamic variables to be prepared prior to any one script's execution, it is suggested that one dynamic variable (say V0) contain a string that identifies the script-set. Each script of the suite expecting the prepared area might then execute the following as it begins: IF NOT ALLOCATED ; Somebody dealloc'd us LOAD ALLOC "Suite.dat" ; Retrieve values from disc IF FAILED GOTO AllocErr ; LOAD failed for some reason ENDIF IF NOT STRCMP V0 "My very own" LOAD ALLOC "Suite.dat" ; Retrieve values from disc IF FAILED GOTO AllocErr ; LOAD failed for some reason ENDIF ... ; OK to proceed For this technique to be effective, the file containing dynamic variables must be updated by individual scripts as they exit. ------------------------------------------------------------------- Note that the test for an allocated area is performed here BEFORE a dynamic variable (V0) is referenced. The dynamic variables are valid syntactically ONLY when an area is allocated. Because the interpre- tor evaluates ALL components of a condition, the following syntax, therefore, generates a syntax error when no area is allocated: IF NOT ALLOCATED or NOT STRCMP V0 "My very own" LOAD ALLOC "Suite.dat" ; Retrieve values from disc IF FAILED GOTO AllocErr ; LOAD failed for some reason ENDIF When "NOT ALLOCATED" is true, "NOT STRCMP V0 ..." is still executed. The reference to V0 in this case would therefore be a syntax error. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 131 J. Flow control methods Some variations on flow control are available through COM-AND. The discussion here centers on the script commands controlling flow con- trol... Note SOFT, HARD, and RTS flow control default conditions may be set through Alt-O... whereas RTS discipline is script-only. 1) XON/XOFF flow control: SET SOFTFLOW ON SET HARDFLOW OFF SET RTSDISCIPLINE ON ; Default condition SET RTSFLOW OFF ; Default condition This is the one everyone understands. XOFFs are sent to tell the opposite side "whoa", and XON send to say "have at it". 2) Hardware flow control (unidirectional): SET SOFTFLOW OFF SET HARDFLOW ON SET RTSDISCIPLINE ON ; Default condition SET RTSFLOW OFF ; Default condition This is the RS232 standard: COM-AND raises RTS before sending a character, and waits for the modem to raise CTS. No provision is made for COM-AND to tell the modem "gimme a break, man". 3) Hardware flow control (modified unidirectional): SET SOFTFLOW OFF SET HARDFLOW ON SET RTSDISCIPLINE OFF SET RTSFLOW OFF ; Default condition SET RTS ... ; Dynamically This is a curiosity implemented for some interesting devices that will not be discussed here. This setting waits for CTS from the modem before sending, but gives control over RTS to a script. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 132 J. Flow control methods (continued) 4) Hardware flow control (bidirectional): SET SOFTFLOW OFF SET HARDFLOW ON SET RTSDISCIPLINE ON ; Default condition SET RTSFLOW ON This is a bidirectional version of hardware flow control. COM-AND waits for CTS before sending. COM-AND raises and lowers RTS to signal its own buffer full conditions to the modem. 5) Software AND hardware flow control (uni/bidirectional): SET SOFTFLOW ON SET HARDFLOW ON SET RTSDISCIPLINE ON ; Default condition SET RTSFLOW ... ; ON or OFF (bi/unidirectional) Soft and Hard flow control (hardware flow control being either uni- or bidirectional) may be selected. In most cases this is the desired setting when the modem requires a hard flow control, and the protocol/carrier requires a soft flow control. The following modems require bidirectional hardware flow control: MultiTech "Multimodem V.32" (possibly all MultiTechs that support PC to modem interface at different speed from the modem to host) US Robotics Courier 9600 HST (???) Telebit T2500 (???) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 133 K. Machine Language Subroutines The script statements OVERLAY and SCALL offer means to extend the script language at a script author's discretion. Needless to say, however, not all systems will support OVERLAY, and development of an OVERLAY proper is difficult, dangerous, and frustrating. The OVERLAY statement loads an EXE or COM file as an overlay to COM-AND. The size of the code/data being loaded as an overlay is limited by available memory. [It is NOT limited to 64K.]. There- fore, a given overlay will not run on all systems... only those with sufficient available memory. An overlay is terminated when COM-AND terminates. It may be cleared by a script itself, with the statement "OVERLAY CLEAR". It is recommended that a script using overlay(s) terminate its overlay when the function is complete - the memory used for the overlay detracts from the space available for SHELL, and accessories. An overlay is entered with the SCALL instruction. SCALL must specify the entry address relative to the first 64K of the overlay space. Thus, all entry points in an overlay MUST be in its first 64K. The overlay is entered through a FAR CALL. Thus, all entry points MUST be FAR procedures (with RETFs, not RETs). SCALL optionally specifies a parameter list to be passed to the over- lay procedure. Parameters on this list are passed by reference through the stack. Thus, all passed parameters MUST be simple variables (Nx, Sx, or Vx), and all passed parameters may be modified. On entry to an overlay procedure, the stack looks like: Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 134 K. Machine Language Subroutines (continued) +------------------------+ ! Segment (16 bits) ! +--- ---+ ! ! SP+4n+2 +------------------------+ 1st parm if 1 or more passed ! ! +--- ---+ ! Offset (16 bits) ! SP+4n +------------------------+ // // ... +------------------------+ ! Segment (16 bits) ! +--- ---+ ! ! SP+6 3rd parm if 3 parm passed +------------------------+ 2nd parm if 2 parm passed ! ! 1st parm if 1 parm passed +--- ---+ ! Offset (16 bits) ! SP+4 +------------------------+ ! Segment (16 bits) ! +--- ---+ ! ! SP+2 +--- Return address ---+ FAR CALL return address ! ! +--- ---+ ! Offset (16 bits) ! SP+0 +------------------------+ Approximately 700 bytes of stack space are available when an overlay is entered. An overlay requiring more stack space must provide its own stack (and mechanism to switch to its own stack when an overlay procedure is entered). The overlay may or may not pop the passed parameter references from the stack on return. COM-AND resets the stack pointer as required. Similarly, the overlay procedure does not have to concern itself with saving and restoring certain registers. COM-AND preserves all registers that it itself requires. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 135 K. Machine Language Subroutines (continued) Parameters passed/returned to/from an overlay have the form: o Nx: the reference Segment:offset points directly to the integer variable. It is 16 bits, in the usual lsb,msb form. o Sx,Vx: the reference Segment:offset points to character 0 of a string variable. String variables are 80 bytes wide, null filled on the right if short. Care must be take NOT to store past 80 characters, as there's NO telling what might be lost. Variables come from different segments. The developer of a machine language subroutine cannot expect all passed variables to have the same segment reference. During an overlay, it should be noted that the BIOS comm support interrupt (for the comm port COM-AND has open) are redirected through COM-AND. Thus, interrupt driven reads (at any speed supported by COM-AND) may be performed through COM-AND. The BIOS 'open' for the comm port COM-AND has open is no-op'd. The development of a nontrivial overlay for a script is difficult, to say the least. Obvious errors will lock the machine up tight, or render the environment (COM-AND) unstable. Subtle errors may have the same effect, or worse. Debugging an overlay is difficult. It is possible to develop an overlay using a high level language. However, each language compiler makes different provisions for the initialization of the environment. An overlay, of course, does not automatically invoke the required initializations (e.g. 80x87 emulation library routines). The developer of any high level language routine serving as a foreign subroutine must take this into account. One final caution. During the development of TALKER.OVL, this author found MicroSoft's EXEPACK to emit executable object that is not relocatable when loaded as an overlay. This author does not recommend use of EXEPACK on overlay code until the code is proven to work, and then only with suspicion. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 136 L. CACMP Included with this release of COM-AND is a separate program, CACMP. Although CACMP has its own (separate document), it will be mentioned here, if only to refer the interested reader to CACMP.DOC. CACMP is a diagnostic and preprocessor for COM-AND scripts. CACMP may be used simply to perform syntax and semantic review of a COM-AND script, or it may be used to strip/preprocess scripts for COM-AND. CACMP syntactically and semantically verifies a given script file. In addition, it will (optionally) perform the following functions: . Partially strip the script to output . Fully strip the script to output . Preprocess the script to output (for speed) The several levels of 'stripping', and 'preprocessing' are discussed in the CACMP documentation. The interested reader is refered there. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 137 M. Script Language (Version 1.x) Version 1.x of PC-VCO included a primitive script facility. That script language paralleled the original script language of PROCOMM version 1.x. The only command whose meaning(s) changed was %F. The %F paralleled the COM-AND Alt-P menu, as PROCOMM's %F paralleled its Alt-P menu. Under most usages this make no difference. The introduction of the 2.x script processor retained the original script language as a subset. A 1.x script command is signalled by a '%' sign. The % must be followed by one, two or three alpha-numeric characters (no blanks) and possibly a quoted string (e.g. "GENIE. CMD"). Text on a line not a part of a valid command is ignored. 1.x script commands may not be mixed on a line with 2.x commands. As of version 2.7 of COM-AND the 1.x script processor is no longer available. This appendix is provided for the decoding (should the need arise) of 1.x scripts. The version 1.x command set was: -> %A Alarm -> %B"str" Default Drive/path -> %C"nn" Call directory number -> %D"str" DOS command -> %En Emulations: unimplemented except for ANSI BBS * %E0 Unimplemented * %E1 Unimplemented * %E2 Unimplemented * %E3 Unimplemented * %E4 Unimplemented * %E5 Unimplemented * %E6 Unimplemented -> %E7 ANSI-BBS * %E8 Unimplemented * %E9 Unimplemented -> %Fn Comm Parms (equivalent to selection 'n' from Alt-P) -> %G Screen dump: unimplemented -> %H Hang up -> %I"str" Wait for incoming string -> %Jn Send macro string 'n', n=0-9 -> %Ks KERMIT server commands: unimplemented * %KMn Unimplemented * %KR Unimplemented * %KS"File_Name" Unimplemented * %KF Unimplemented * %KL Unimplemented Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 138 M. Script Language (Version 1.x, continued) -> %Ls Log commands -> %LO "File_Name" Open log using "File_Name" (no default) -> %LH Hold logging -> %LR Resume logging -> %LC Close log -> %M"str" Display a message on the screen -> %N"str" Prompt for input and send -> %Os BIOS/Direct screen writes -> %OB Write to screen through BIOS -> %OD Write to screen direct -> %P"nn" Seconds to wait for an incoming string -> %Q Quit program -> %R"nn" Redial delay value -> %Ss Sound controls. -> %SY Allow alarm sounds -> %SN No alarm sounds (though alarm will delay) -> %ST"nn" Set delay for alarm (value in seconds) -> %T"str" Transmit string -> %Us Miscellaneous: implemented as applicable -> %U1 Clear screen * %U2 Send CR as CR: unimplemented * %U3 Send CR as CR/LF: unimplemented -> %U4 Set full duplex (echoplex) -> %U5 Set half duplex -> %U6 Send Break signal * %U7 Set line wrap on: unimplemented * %U8 Set line wrap off: unimplemented * %U9 Set Scroll on: unimplemented * %U0 Set Scroll off: unimplemented -> %Vs Miscellaneous: VCO specific subcommands * %V0 Unimplemented (PC-VCO used for Voice) * %V1 Unimplemented (PC-VCO used for Voice) * %V2 Unimplemented (PC-VCO used for Voice) %V3 Blank line suppression on (Alt-G) %V4 Blank line suppression off (Alt-G) %V5 High bit masking on (Alt-Z) %V6 High bit masking off (Alt-Z) %V7 Chat mode on (Alt-A) %V8 Chat mode off (Alt-A) %V9 WXMODEM send allowed (not used now) %VA WXMODEM send not allowed (not used now) %VB WXMODEM receive allowed (not used now) %VC WXMODEM receive not allowed (not used now) %VD"File_Name" Unimplemented (PC-VCO FLB fname) %VE"File_Name" Unimplemented (PC-VCO EXC fname) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 139 M. Script Language (Version 1.x, continued) -> %Vs (continued) * %VF Unimplemented (PC-VCO use PLINK/CIS) * %VG Unimplemented (PC-VCO use GEnie/Delphi) -> %W"nn" Wait for a specified # seconds -> %Xs XMODEM receive/send -> %XR"File_Name" -> %XS"File_Name" -> %Ys ASCII Send * %YP"nn" Set pacing: unimplemented -> %YT"File_name" Transmit file_name using ASCII send %Y0"str" Set host prompt character %Y1 Turn off host prompt character %Y2 Transmit linefeeds on %Y3 Transmit linefeeds off %Y4 Tab expansion on %Y5 Tab expansion off %Y6"nn" Set intercharacter delay (in milliseconds) -> %Zs Translate tables: unimplemented. * %ZY Translate table on: unimplemented * %ZN Translate table off: unimplemented Multiple 1.x commands may be placed on a single line. SYNTAX errors are reported. On 'end-of-file', COM-AND returns to the normal interactive mode (unless %Q was specified in the script). -------------------------------------------------------------------- The notation '->' to the left of a script command indicates that it IS a part of the PROCOMM script language. Unmarked extensions were added for COM-AND, to provide its features to script file users. -------------------------------------------------------------------- The notation '*' to the left of a script command indicates that it is unimplemented (but will be accepted). Commands marked 'unim- plemented' are parsed and accepted by COM-AND, but not executed. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 140 N. Language Summary Version 2.1 of COM-AND included a script processor that performed scripts written for PROCOMM 2.4.2 and also extended the script language considerably (substring extraction, concatenation, ...). When PROCOMM Plus was released, COM-AND's script language was again extended, to include ASPECT as a subset, and also to add functions requested by COM-AND users. The resulting language syntax is summarized below. Between COM-AND 2.1 and COM-AND 2.2 a certain few instructions and usages did change, most notably the indexing of substrings. COM-AND 2.1 numbered characters in substrings from 1. ASPECT added substring functions, but numbered characters from 0. This author could not release a script language that contained both usages, and defered to PCPlus. For any inconvenience to COM-AND users, I apologize. ----------------------------------------------------------------- The notation '->' to the left of a script command below indicates that it IS compatible with the ASPECT script language. ----------------------------------------------------------------- The notation '*' to the left of a script command indicates that it is unimplemented (but will be accepted). Commands marked 'unim- plemented' are parsed and accepted by COM-AND. SYNTAX errors in command formation are not necessarily reported. Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 141 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 11: ACCESSORY <string> ; Accessory directory entry # 1-50 11: -> ADD Nx Ny Nz ; Nz = Nx+Ny 12: -> ALARM [<number>] ; Time in seconds 12: ALOAD <string> ; Load accessory directory 12: ALLOCATE <number> ; Allocate up to 100 variables 12: ANAME Sx <number> ; Acc Dir entry name 13: APGM Sx <number> ; Acc Dir program invocation 13: ASCRIPT Sx <number> ; Acc Dir script invocation 13: -> ASSIGN Sx <string> ; Set a value into Sx 13: ASUBDIR Sx <number> ; Acc Dir subdirectory field 13: -> ATGET row col attr len Sx ; GET performed with positioning 14: -> ATOI Sx Nx ; Convert a str variable to num 14: -> ATSAY row col attr <string> ; MESSAGE performed with positioning 14: ATSCR row col len Sx ; Read screen at location for len 14: -> BOX row col row col attr ; Draw a box (clear within) 15: -> BREAK [<number>] ; Time in milliseconds 15: -> BYE ; Exit script and pgm - leave DTR 15: -> CASE (<string>!<number>) ; Within SWITCH/ENDSWITCH 15: -> CHDIR <string> ; Change d:\path 16: -> CLEAR <attr> ; Clear screen 16: CLOG OPEN <string> ; Open call-logging file by name 16: CLOG CLOSE ; Close call-logging 16: CLOG <string> ; Write to call-log if open 17: COLOR <attr> ; Set screen text color 17: COMBASE <port> Nx ; Get base addr of COMx 17: COMPARMS Sx ; Return current comm parm settings 17: COMVECTOR <port> Nx ; Get vector # for COMx 18: CONCAT Sx [(##)!*] <string> ; Concatenate text to Sx [at col ##] 18: -> CONNECT ; Exit script 18: CRC <string> Nx ; Compute buffer CRC 19: CTOI Sx Nx ; Character to value conversion 19: -> CUROFF ; Turn off cursor (EXIT turns on) 19: -> CURON ; Turn on cursor (if off) 19: -> CURSOR Nx Ny ; Read cursor (nx=row,ny=col) 19: -> CWHEN [(#)] ; # = 0,1,2,...9 20: -> DATE Sx (0!1) ; System date 20: DBOX row col row col attr ; Double line box (clear within) 20: DEALLOCATE ; Deallocate dynamic variables 20: -> DEC Nx ; Decrement a numeric variables 21: DECRYPT <string><string><string>; Decrypt a file to a file using psw 21: -> DEFAULT ; Within SWITCH/ENDSWITCH Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 142 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 21: DEFTIME <number> ; WAITFOR, etc in seconds 21: DELETE <string> ; Delete a file by name (SUCCESS) 22: -> DIAL <string> ; Dialing directory entry # 1-100 22: -> DIR <string> ; Perform Alt-F directory function 22: DIRECTORY Sx [<number>] ; Return dialing entry name 23: -> DIV Nx Ny Nz ; Nz = Nx/Ny 23: DLDIR Sx ; Read current download d:subdir 23: DLOAD <string> ; File name argument 23: DNUMBER Sx [<number>] ; Return dialing entry number 24: DO ; Begin a DO-Loop clause (see UNTIL) DO ; Start loop here ; Example ... ; Example UNTIL <condition> ; Example 25: -> DOS <string> [WAIT] ; Perform a DOS command 25: DPARMS Sx [<number>] ; Return dialing entry parms 25: DSCRIPT Sx [<number>] ; Return dialing entry script 26: DWINDOW row,col,row,col ; Set scrolling region 26: DWINDOW CLEAR ; Reset scrolling region to original 26: EBL Sx <EBL var> ; Access EBL global (%A-%O, &...) 27: EBLSET &<name> Sx ; Set EBL extended variable 27: -> ELSE ; Within IF/ENDIF 27: ELSE statement ; ENDIF not required this form 27: -> EMULATE (TTY!ANSI!VIDTEX!VT100!VT52) 28: ENCRYPT <string><string><string> [DES!SIM!AUT] ; Encrypt a file 15: -> ENDCASE ; Terminates CASE or DEFAULT clause 35: ENDFOR ; Terminates a FOR Loop 44: -> ENDIF ; Terminates an IF clause 75: -> ENDSWITCH ; Terminates a SWITCH clause 81: ENDWHILE ; Terminates a WHILE clause 28: ENVIRON Sx <string> ; Return environment variable value 29: -> EXECUTE <string> ; Chain to new script 29: -> EXIT ; Terminate script 29: -> FATSAY row col attr <fmtstr> <parms> ; Fmttd MESS performed with pos 30: FATTR Sx <file> ; File attribute, binary, (SUCCESS) 31: FCALL <file> ; CALL a file as a subroutine 32: -> FCLOSEI ; Close input file 32: -> FCLOSEO ; Close output file 32: FDATE Sx <file> [0!1] ; Date last modified (SUCCESS flag) 32: FFIRST Sx ; Initialize wildcard (SUCCESS flag) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 143 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 33: -> FGETC Sx ; Read a character 33: -> FGETS Sx ; Read a record 33: -> FIND Sx <string> [Nx] ; Test for index in Sx 34: FNEXT Sx [QUAL] ; Next file after FFIRST (SUCCESS) 34: -> FOPENI Sx [TEXT!BINARY] ; Open a file for input 34: -> FOPENO Sx [TEXT!BINARY!APPEND] ; Open a file for output 35: FOR Nx = <val> <val> [<val>] ; FOR Loop (init,final,step) FOR Nx = <val> <val> [<val>] ; Example ... ; Example ENDFOR ; Example 36: -> FPUTC Sx ; Read a character 36: -> FPUTS Sx ; Read a record 36: -> FREAD Sx Nx Ny ; Read a record (Nx may be literal) 37: FREE Sx <string> ; Get available space on <disc> 37: FRESTORE[I!O] ; Restore position from last FSAV 37: FRETURN ; RETURN from an FCALL 38: FSAVE[I!O] ; Save input/output file position 38: FSAVE[I!O] CLEAR ; Clear stack of saved positions 38: FSAVE[I!O] SHIFT ; Shift stack of saved pos down 1 38: FSAVE[I!O] POP ; Throw away last saved position 38: FSIZE Sx <file> ; File size, 7 digits, (SUCCESS) 38: FTIME Sx <file> [0!1] ; Time last modified (SUCCESS flag) 39: -> FWRITE Sx Nx ; Write a record (Nx may be literal) 39: -> GET Sx [<number>] ; <number> = maximum length 40: -> GETFILE ASCII <string> ; A.K.A. Buffer capture 40: -> GETFILE BYMODEM ; Batch YMODEM (True ... (TM)) 40: -> GETFILE BYMODEMG ; Streaming YMODEM (batch) 40: -> GETFILE CISB ; CompuServe B-protocol 40: -> GETFILE KERMIT ; Kermit or SuperKermit 40: GETFILE QUICKB ; CompuServe Quick B-protocol 40: -> GETFILE RXMODEM <string> ; Relaxed CRC or Checksum XMODEM 40: -> GETFILE WXMODEM <string> ; Windowed XMODEM 40: -> GETFILE XMODEM <string> ; CRC or Checksum XMODEM 40: -> GETFILE YMODEM <string> ; Simple YMODEM (not True ... (TM)) 40: GETFILE ZMODEM ; ZMODEM (batch) 41: -> GOSUB <string> ; Call a subroutine (and return) 42: -> GOTO <string> ; Branch (not into IF or SWITCH) 43: -> HANGUP ; Disconnect call * HELP ; Help processor (unimplemented) * HOST ; Host mode (unimplemented) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 144 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 44: IF [NOT] ALPHA Sx ; Test for alpha char 44: IF [NOT] ALLOCATED ; Test for dynamic variables 44: -> IF [NOT] CONNECTED ; Test modem carrier (CD) 44: IF [NOT] CONTROL Sx ; Test for control char 44: -> IF [NOT] EOF ; Test for EOF on input file 44: IF [NOT] ERROR ; Test last instruction 44: -> IF [NOT] FAILURE ; .. NOT SUCCESS 44: IF [NOT] FCALLED ; Test for FCALL return required 44: IF [NOT] FKEY ; Test for ftn key pending 44: IF [NOT] FLAG [(#)] ; Test flag variable 44: IF [NOT] FCALLED ; Test for FCALL of script 44: IF [NOT] FIND Sx Sy [Nx] ; Test for Sx .within. Sy 44: -> IF [NOT] FOUND ; Test last FIND statement 44: IF [NOT] FULL ; Test if we have XOFFed host 44: -> IF [NOT] HITKEY ; Test for keypress pending 44: IF [NOT] ISDLFILE Sx ; Test for file presence 44: -> IF [NOT] ISFILE Sx ; Test for file presence 44: IF [NOT] ISSCFILE Sx ; Test for file presence 44: -> IF [NOT] LINKED ; If script executed from dialing 44: -> IF [NOT] MONO ; Test for monochrome adapter 44: IF [NOT] NULL Sx ; Test for Sx blank or null 44: IF [NOT] NUMERIC Sx ; Test for numeric character 44: IF [NOT] OVERLAY ; Test for overlay loaded 44: IF [NOT] PRINTER ; Test for PRINTER ON 44: IF [NOT] RECEIVE ; Test for comm chars pending 44: IF [NOT] SPECIAL Sx ; Test for special character 44: IF [NOT] STRCMP Sx Sy ; Test Sx = Sy 44: -> IF [NOT] SUCCESS ; Test last statement 44: IF [NOT] TRACE ; Test for tracing 44: -> IF [NOT] WAITFOR ; Test last WAITFOR statement 44: IF [NOT] XOFF ; Test for XOFF condition 44: -> IF [NOT] ZERO Nx ; Test for Nx = 0 44: -> IF [NOT] GT!LT!GE!LE!EQ Nx Ny ; Test for Nx .condition. Ny 44: IF [NOT] NE Nx Ny ; Test for not equal 44: IF [NOT] Nx GT!LT!GE!LE!EQ Ny ; Test for Nx .condition. Ny Usual form Alternative form Alternative form -------------------+--------------------+---------------------- -> IF condition | IF condition stmt | IF condition [stmts] | | [stmts] -> ELSE | | ELSE statement [stmts] | | -> ENDIF | (not ASPECT form) | (not ASPECT form) Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 145 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 49: -> INC Nx ; Increment a numeric var 49: -> INIT Nx <number> ; Initialize a numeric variable 50: INPUT Nx <address> ; Machine level INPUT 50: ISDLFILE <string> ; Test for presence of a dload file 50: -> ISFILE <string> ; Test for presence of a file 51: ISSCFILE <string> ; Test for presence of a script file 51: -> ITOA Nx Sx ; Numeric to string conversion 51: ITOC Nx Sx ; Value to character conversion * KERMSERV FINISH ; Unimplemented * KERMSERV GETFILE ; Unimplemented * KERMSERV LOGOUT ; Unimplemented * KERMSERV SENDFILE ; Unimplemented 52: -> KEYGET Sx ; Read ('a', esc='1b', F1='3b00') 52: -> KFLUSH ; Flush keyboard buffer 52: LD Sx <number> ; Return long dist string 1,2,3,4 52: LEGEND <string> ; Text for status line 53: LENGTH Sx Nx ; Compute length of string 53: LJ Sx ; Left justify string variable 53: LOAD (DIAL!MACR!ACCE!DEFA!ALLOC) [parms] ; Load file data 53: -> LOCATE <number> <number> ; Position cursor <row> <col> 54: -> LOG OPEN <string> ; Open disk/PRN logging 54: -> LOG CLOSE ; Close disk/PRN logging 54: -> LOG SUSPEND ; Suspend disk/PRN logging 54: -> LOG RESUME ; Resume disk/PRN logging 54: LOG MARKED (ON!OFF) ; Set/reset log timestamping 54: LOWER Sx ; Lower case contents of Sx 54: -> MACRO <num> [Sx] ; <num> = 0-9, Sx optional 55: MANUAL <number> ; Invoke an interactive window 55: -> MATGET row col attr len Sx ; MGET performed with positioning 55: -> MDIAL <string> ; Dial number in Sx manually 56: MDIR <string> ; Create a subdirectory 56: -> MESSAGE <string> ; Write text to local console 56: -> MGET Sx <number> ; <number> = max length 56: -> MLOAD <string> ; File name argument 57: MSR Nx ; Read the modem status register 57: -> MUL Nx Ny Nz ; Nz = Nx*Ny 58: Nx = expression ; Compute a value and assign it 59: OUTPUT <address> Nx ; Machine level OUTPUT 59: ON ESCAPE GOSUB <label> ; Action on operator escape 59: ON ESCAPE CLEAR ; Clear set action 59: ON SILENCE GOSUB <label> ; Action on receive timeout 59: ON SILENCE CLEAR ; Clear set action Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 146 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 60: OVERLAY <file> ; Load .EXE or .COM overlay 60: OVERLAY CLEAR ; Release overlay area 61: -> PAUSE [<number>] ; Time in seconds 61: PERFORM <string> ; Perform string as command 61: PLAY <string> ; Play a music string 61: PRESERVE Sx ; Modify to avoid edits 62: -> PRINTER (ON!OFF) ; Turn printer copy on/off 62: PRINT <string> ; Send <string> to LP1 printer 62: -> QUIT ; Terminate script 63: RDIR <string> ; Remove a subdirectory 63: READ Sx Nx Ny ; Read a record (Nx may be literal) 63: RENAME Sx Sy ; Rename a file by name (SUCCESS) 64: RESET ; Restore dfts to load-time values 64: RESTORE ; Restore last saved area on screen 64: -> RETURN ; Return from GOSUB 64: REWIND ; Rewind input (SUCCESS) 64: -> RFLUSH ; FLush receive buffer 65: -> RGET Sx [<number> [<number>]] ; <length> <delay in seconds> 65: RND <modulus> Nx ; Return random number 65: RJ Sx ; Right justify string variable 66: -> RUN <string> [WAIT] ; Load and execute a program 66: SAVE row col row col ; Save an area on the screen 66: SCALL <addr> [parms[,parms]] ; Call an overlay procedure 67: -> SCROLL cnt row col row col attr ; Scroll a region on the screen 67: SCREEN row col row col attr Sx ; Multiline screen display 68: -> SENDFILE ASCII <string> ; A.K.A. Buffer capture 68: -> SENDFILE BYMODEM <string> ; Batch YMODEM (True ... (TM)) 68: -> SENDFILE BYMODEMG <string> ; Streaming YMODEM (batch) 68: -> SENDFILE CISB ; CompuServe B-protocol 68: -> SENDFILE KERMIT <string> ; Kermit or SuperKermit 68: SENDFILE QUICKB ; CompuServe Quick B-protocol 68: -> SENDFILE RXMODEM <string> ; Relaxed CRC or Checksum XMODEM 68: -> SENDFILE WXMODEM <string> ; Windowed XMODEM 68: -> SENDFILE XMODEM <string> ; CRC or Checksum XMODEM 68: -> SENDFILE YMODEM <string> ; Simple YMODEM (not True ... (TM)) 68: SENDFILE ZMODEM <string> ; ZMODEM transfer (batch) 84: -> SET <subcommand> ; See below 68: -> SHELL ; SHELL to DOS (must exit manually) 69: SNAME Sx ; Name of current script file * SNAPSHOT ; Unimplemented 69: -> SOUND Nx Ny ; Sound frequency Nx for Ny msecs 69: SSIZE Nx ; Return # screen lines Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 147 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 70: STACK <string> ; Store <string> in BIOS kbd buffer 70: STACK CLEAR ; Clear BIOS keyboard buffer 70: STORE (DIAL!MACR!ACCE!DEFA!ALLOC) [parms] ; Create new setting file 71: -> STRCAT Sx Sy ; Concatenate 2 strings 71: -> STRCMP Sx Sy ; Compare Sy to Sx (case sensitive) 71: -> STRCPY Sx Sy ; ASSIGN Sy to Sx 72: -> STRFMT Sx <fmtstr> <parms> ; Fmt Sx using <fmtstr> and <parm> 73: -> SUB Nx Ny Nz ; Nz = Nx-Ny 73: SUBDIR Sx ; Set d:subdir into Sx 73: -> SUBSTR Sx Sy <number> <number> ; Take substr from Sy, place in Sx 74: SUSPEND FOR Nx Ny ; Suspend for duration (h,m) 74: -> SUSPEND UNTIL Nx Ny ; Suspend until time (military fmt) 75: -> SWITCH (Sx!Nx) ; Variable to be tested -> SWITCH (Sx!Nx) ; Variable to be tested -> CASE (<string>!<number>) ; Match Sx and <string> ... ; .. Execute if they match -> ENDCASE ; Each case must have an ENDCASE -> CASE <string> ; <String> = "_NULL" -> empty ... -> ENDCASE ; End of second case ... -> DEFAULT ; DEFAULT executed if no case ... ; .. above matched -> ENDCASE ; End of DEFAULT case, too -> ENDSWITCH ; End of SWITCH domain 76: Sx(m:n) = expression ; Concatenate strings and assign 76: -> TERMINAL ; Exit script 77: -> TIME Sx [0!1] ; System time (1 -> military fmt) 77: -> TRACE (ON!OFF) ; Script tracing 77: -> TRANSMIT <string> ; Send exactly <string> 77: TSINCE [(#)] Nx Ny Nz ; Read time since timer (#) in h,m,s 78: -> TYPE <string> ; Display contents of a file (Alt-W) 78: UNTIL <condition as IF> ; Terminates a DO-Loop 78: UPDATE ; Update dft file 78: UPPER Sx ; Upper case contents of Sx 78: VERSION Nx ; Read COM-AND VERSION # 79: -> WAITFOR <string> [<number>] ; Optional time in seconds 79: WCLOSE ; Close an open window 80: -> WHEN [(#)] <string> <string> ; <target> <response> Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 148 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 81: WHILE <condition> ; Begins a conditional loop if true WHILE <condition> ; Example ... ; Example ENDWHILE ; Example 82: WOPEN row col row col attr [label] ; Open window (label optional) 83: WRITE Sx [Nx] ; Write a record (Nx optional) 84: SET 25 ; CGA/Mono 84: SET 43 ; EGA mode 84: SET ACCE NAME # <string> ; Acc Dir entry name field 84: SET ACCE SUBD # <string> ; Acc Dir entry subdir field 84: SET ACCE PGM # <string> ; Acc Dir entry pgm field 84: SET ACCE SCRI # <string> ; Acc Dir entry script field 84: SET ADVERT (ON!OFF) ; Set initial advert on/off 84: -> SET ALARM (ON!OFF) ; Disable alarm sound (see ATIME) 84: SET ANYWHEN (ON!OFF) ; WHEN exact (off), or substr (on) 98: -> SET ASCII <subcommand> ; See below 84: -> SET ATIME <number> ; Alarm time in seconds 84: -> SET BACKSPACE IN (NONDEST!DEST) ; Bkspace function when rcv'd 84: -> SET BACKSPACE OUT (BACK!DELETE) ; Bkspace function when sent 84: SET BAR <attr> ; Set status line color 84: -> SET BAUDRATE (300!1200!2400!4800!9600!19K!38K!56K!115K) 84: SET BELL # ; Set bell tone in Hz 84: SET BKSCREEN # ; Backscreen size 0-64 84: -> SET BREAK <number> ; Time in milliseconds 84: SET BSUPPRESS (ON!OFF) ; Blank line suppression 84: SET CALLLOG (ON!OFF) ; Set/reset call logging 84: SET CDISPLAY (ON!OFF) ; Control character display 84: SET CDRESPECT (ON!OFF) ; Set/reset CD respect 84: SET CHAT (ON!OFF) ; Chat mode 84: SET CHLINES # ; Specify chat window size 84: SET CLOCK (ON!OFF!NEW) ; Screen clock (new -> reset time) 84: SET COLOR (ON!OFF) ; Set/reset color screen 84: SET COMBASE <port> Nx ; Specify base address COMx 84: SET COMVECTOR <port> Nx ; Specify vector # COMx 84: -> SET CR (CR!CR_LF) ; CR received as CR or CR/LF 84: -> SET CR_IN (CR!CR_LF) ; CR received as CR or CR/LF * SET CR_OUT (CR!CR_LF) ; Unimplemented 84: -> SET DATABITS (7!8) ; Set comm parm Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 149 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 84: SET DEFAULT <attr> ; Set menu window color 84: SET DBLCLICK # ; Dbl click interval in MS 84: SET DIAL NAME # <string> ; Dial dir entry name field 84: SET DIAL NUMB # <string> ; Dial dir entry number field 84: SET DIAL RATE # <string> ; Dial dir entry rate field 84: SET DIAL PARI # <string> ; Dial dir entry parity field 84: SET DIAL DATA # <string> ; Dial dir entry dbits field 84: SET DIAL STOP # <string> ; Dial dir entry stop field 84: SET DIAL SCRI # <string> ; Dial dir entry script field 84: -> SET DISPLAY (ON!OFF) ; PC+ 1.1 SET RDISP equivalent 84: -> SET DLDIR <string> ; Set d:\path for downloads 84: SET DOSLEVEL <number> ; Set pgm error level for batches 84: SET DPREFIX <string> ; Specify dialing prefix 84: SET DROPDTR (ON!OFF) ; Set hangup method 84: SET DSUFFIX <string> ; Specify dialing suffix 84: SET DTR (ON!OFF) ; Raise/lower DTR to modem 84: -> SET DUPLEX (HALF!FULL) ; Keyboard echo * SET ENQ ON ; Unimplemented 84: SET ENQ (OFF!CISB) ; Automatic CIS file up/dn, VIDTEX 84: SET EXIT <scriptname> ; Script on Alt-X, BYE 84: SET EXQUery (ON!OFF) ; Set exit query flag 84: SET FAILURE (ON!OFF) ; Set/reset FAILURE flag (IF test) 84: SET FLAG [(#)] (ON!OFF) ; Set/reset flags 84: -> SET FLOWCTRL (ON!OFF) ; XON/XOFF flow control 84: SET FOUND (ON!OFF) ; Set/reset FOUND flag (IF test) 84: -> SET HARDFLOW (ON!OFF) ; RTS/CTS discipline 84: SET HMOUSE # ; Set mouse horiz sensitivity * SET HOSTPSWD <string> ; Unimplemented 84: SET INAFTER (ON!OFF) ; Set init modem after hangup 84: SET KBDBUFFER (ON!OFF) ; Keyboard display buffer 99: -> SET KERMIT <subcommand> ; See below 84: SET LD # <string> ; LD dir entry (1-4) 84: SET LINKED (ON!OFF) ; Set/reset LINKED flag (IF test) 84: SET MACRO # <string> ; Macro dir entry (0-9) 84: SET MASK (ON!OFF) ; 7/8 bit masking 84: SET MCONNECT <string> ; Specify modem connect string 84: SET MDCHar <value> ; Set modem delay char ASCII value 84: SET MDELAY # ; Specify intercharacter delay -> SET MENUMODE (ON!OFF) ; Turn on/off menu mode 84: SET MESCAPE <string> ; Specify modem escape string 84: SET MHANGUP <string> ; Specify hangup string Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 150 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 84: SET MINIT <string> ; Specify modem init string 84: SET MUSIC (ON!OFF) ; Set/reset music escape sequences 84: -> SET PARITY (EVEN!ODD!NONE) ; Set comm parm 84: SET PCJR (ON!OFF) ; Suspend comm during disk I/O 84: -> SET PORT (COM1!COM2!COM3!COM4) ; Set comm parm 84: SET QUIET (ON!OFF) ; Suppress bells 84: -> SET RDELAY <number> ; Reconnect delay, in seconds 84: SET RDISPLAY (ON!OFF) ; Receive character display 84: SET RDMAX <number> ; Set redial limit count 84: SET RECHO (ON!OFF) ; Received character echo (back out) 84: -> SET REMOTE (ON!OFF) ; Set/reset remote cmd processing 84: SET RLEOK (ON!OFF) ; Allow/disallow RLE's 84: SET RMODE (ASCII!BINARY) ; RGET implements BS/rubout 84: SET RTS (ON!OFF) ; Set/reset modem RTS bit 84: SET RTSD (ON!OFF) ; Set/reset modem RTS discipline 84: SET RTSF (ON!OFF) ; Set/reset RTS flow control * SET SCROLL (ON!OFF) ; Unimplemented * SET SHELLPSWD <string> ; Unimplemented 84: SET SILENCE <seconds> ; Set ON SILENCE duration 84: SET SLOWOUT (ON!OFF) ; Set slow writes 84: -> SET SOFTFLOW (ON!OFF) ; XON/XOFF flow control * SET SOUND (ON!OFF) ; Unimplemented 84: -> SET STOPBITS (1!2) ; Comm parm 84: SET SUCCESS (ON!OFF) ; Set/reset SUCCESS flag (IF test) 84: -> SET SWRITE (BIOS!DIRECT!DOS) ; Screen I/O update method 84: SET TEXT <attr> ; Set text window color 84: SET TIMER [(#)] ; Set timer number (#) to now 84: -> SET TRANSLATE (ON!OFF) ; Toggle translation 84: SET TTHRU (ON!OFF) ; Set typethrough unconditionally 84: SET TUNE <string> ; Set alarm tune using string * SET TXPACE <number> ; Implemented as SET ASCII CHARPACE 84: SET VMOUSE # ; Set mouse vert sensitivity 84: SET WAITFOR (ON!OFF) ; Set/reset WAITFOR flag 84: SET WATCHDOG <secs> ; Set XOFF timeout in seconds * SET WRAP (ON!OFF) ; Unimplemented 84: SET XSUI <number> ; Set xfer screen update interval 101: SET ZMODEM <subcommand> ; See below Version 2.7: 901015 Appendices COM-AND: IBM PC Communication Script Language Page 151 N. Language Summary (continued) Page Syntax Comment ------ ------------------------------- ----------------------------- 98: -> SET ASCII BLANKEX (ON!OFF) ; Blank line expansion ASCII send 98: -> SET ASCII CHARPACE <number> ; Time in MS between characters * SET ASCII DN_CR (CR!CR_LF!STRIP); Unimplemented * SET ASCII DN_LF (CR!CR_LF!STRIP); Unimplemented 98: -> SET ASCII ECHO (ON!OFF) ; Force Echo during SENDFILE ASCII 98: SET ASCII FLOW (ON!OFF) ; ASCII send flow control used 98: -> SET ASCII LINEPACE <number> ; Delay between lines (1/10ths sec) 98: -> SET ASCII PACECHAR <number> ; Prompt from host (Decimal value) 98: SET ASCII QUIET (ON!OFF) ; Disable alarm after SENDFILE ASCII 98: SET ASCII TABEX (ON!OFF) ; Tab expansion ASCII send * SET ASCII UP_CR (CR!CR_LF!STRIP); Unimplemented 98: -> SET ASCII UP_LF (LF!CR_LF!STRIP); CR_LF unimplemented 98: SET ASCII UP_Z (STOP!SEND) ; Terminate ASCII send on ctl-z 99: -> SET KERMIT 8QUOTE <number> ; Decimal ascii value 99: -> SET KERMIT BLOCKCHECK (1!2!3) ; Block check character length 99: -> SET KERMIT CQUOTE <number> ; Decimal ascii value 99: -> SET KERMIT EOLCHAR <number> ; Decimal ascii value * SET KERMIT HANDSHAKE <number> ; Decimal ascii value * SET KERMIT FILETYPE (TEXT!BINARY); Unimplemented 99: SET KERMIT MARK <number> ; Decimal ascii value * SET KERMIT PACKSIZE <number> ; Decimal ascii value 99: -> SET KERMIT PADCHAR <number> ; Decimal ascii value 99: -> SET KERMIT PADNUM number ; Number of pads 99: SET KERMIT REPEAT <number> ; Decimal ascii value 99: SET KERMIT WINDOW <number> ; Decimal ascii value 101: SET ZMODEM AUTO (ON!OFF) ; Auto downloading 101: SET ZMODEM BLOCK <number> ; Decimal ascii value 101: SET ZMODEM RECOVER (ON!OFF) ; Download recovery Version 2.7: 901015 Appendices